vidply 1.2.1 → 1.2.3

package/src/controls/KeyboardHelp.ts

@@ -0,0 +1,326 @@
+/**
+ * Keyboard Shortcuts Help Dialog
+ *
+ * A focus-trapped modal listing the player's active keyboard shortcuts.
+ * Built lazily from `player.options.keyboardShortcuts` so it always reflects
+ * the live bindings (including consumer overrides). Mirrors the focus, escape
+ * and return-focus behaviour of SettingsDialog for a consistent, accessible UX.
+ */
+
+import { DOMUtils } from '../utils/DOMUtils.js';
+import { createIconElement } from '../icons/Icons.js';
+import { i18n } from '../i18n/i18n.js';
+import type { Player } from '../core/Player.js';
+import type { KeyboardShortcuts } from '../types/options.js';
+
+/**
+ * Display order for the shortcut rows. Only actions that are both listed here
+ * and have at least one bound key are rendered, so removing a binding hides
+ * its row automatically.
+ */
+const ACTION_ORDER: Array<keyof KeyboardShortcuts> = [
+  'play-pause',
+  'seek-backward',
+  'seek-forward',
+  'volume-up',
+  'volume-down',
+  'mute',
+  'captions',
+  'caption-style-menu',
+  'speed-down',
+  'speed-up',
+  'speed-menu',
+  'quality-menu',
+  'chapters-menu',
+  'transcript-toggle',
+  'fullscreen',
+  'help'
+];
+
+/**
+ * Feature-specific actions only make sense when the matching feature actually
+ * exists on this player (e.g. there's no point listing the captions shortcut
+ * for a video without captions). Each value is the key under
+ * `player.controlBar.controls` whose presence proves the feature is available
+ * and enabled for this player. Actions not listed here (play/pause, seek,
+ * volume, mute, help) are always relevant for any audio/video player.
+ */
+const ACTION_REQUIRES_CONTROL: Partial<Record<keyof KeyboardShortcuts, string>> = {
+  captions: 'captions',
+  'caption-style-menu': 'captionStyle',
+  'speed-down': 'speed',
+  'speed-up': 'speed',
+  'speed-menu': 'speed',
+  'quality-menu': 'quality',
+  'chapters-menu': 'chapters',
+  'transcript-toggle': 'transcript',
+  fullscreen: 'fullscreen'
+};
+
+export class KeyboardHelp {
+  player: Player;
+  isOpen = false;
+  overlay: HTMLElement | null = null;
+  private _triggerElement: HTMLElement | null = null;
+  private _keydownHandler: ((e: KeyboardEvent) => void) | null = null;
+  private _content: HTMLElement | null = null;
+
+  constructor(player: Player) {
+    this.player = player;
+  }
+
+  private get prefix(): string {
+    return this.player.options.classPrefix;
+  }
+
+  /**
+   * Turn a raw KeyboardEvent.key value into a human-readable label. Arrow
+   * keys become universally understood glyphs; the space bar and single
+   * letters are normalised for legibility.
+   */
+  private formatKey(key: string): string {
+    switch (key) {
+      case ' ':
+        return i18n.t('help.keys.space');
+      case 'ArrowUp':
+        return '\u2191';
+      case 'ArrowDown':
+        return '\u2193';
+      case 'ArrowLeft':
+        return '\u2190';
+      case 'ArrowRight':
+        return '\u2192';
+      case 'Escape':
+        return 'Esc';
+      default:
+        return key.length === 1 ? key.toUpperCase() : key;
+    }
+  }
+
+  private createElement(): HTMLElement {
+    const titleId = `${this.prefix}-help-title-${this.player.instanceId}`;
+
+    const overlay = DOMUtils.createElement('div', {
+      className: `${this.prefix}-settings-overlay ${this.prefix}-help-overlay`,
+      attributes: {
+        role: 'dialog',
+        'aria-modal': 'true',
+        'aria-labelledby': titleId
+      }
+    });
+    overlay.style.display = 'none';
+
+    const dialog = DOMUtils.createElement('div', {
+      className: `${this.prefix}-settings-dialog ${this.prefix}-help-dialog`
+    });
+
+    const header = DOMUtils.createElement('div', {
+      className: `${this.prefix}-settings-header`
+    });
+
+    const title = DOMUtils.createElement('h2', {
+      textContent: i18n.t('help.title'),
+      attributes: { id: titleId }
+    });
+
+    const closeButton = DOMUtils.createElement('button', {
+      className: `${this.prefix}-button ${this.prefix}-settings-close`,
+      attributes: {
+        type: 'button',
+        'aria-label': i18n.t('help.close')
+      }
+    });
+    closeButton.appendChild(createIconElement('close'));
+    closeButton.addEventListener('click', () => this.hide());
+
+    header.appendChild(title);
+    header.appendChild(closeButton);
+
+    const content = DOMUtils.createElement('div', {
+      className: `${this.prefix}-settings-content`
+    });
+    this._content = content;
+    content.appendChild(this.buildShortcutList());
+
+    dialog.appendChild(header);
+    dialog.appendChild(content);
+    overlay.appendChild(dialog);
+
+    overlay.addEventListener('click', (e: MouseEvent) => {
+      if (e.target === overlay) {
+        this.hide();
+      }
+    });
+
+    this._keydownHandler = (e: KeyboardEvent) => {
+      if (!this.isOpen || !this.overlay) return;
+
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        this.hide();
+        return;
+      }
+
+      // Trap Tab within the dialog (WCAG 2.1.2, 2.4.3).
+      if (e.key === 'Tab') {
+        const focusable = Array.from(
+          this.overlay.querySelectorAll<HTMLElement>(
+            'button, [href], select, input, textarea, [tabindex]:not([tabindex="-1"])'
+          )
+        ).filter((el) => !el.hasAttribute('disabled') && el.offsetParent !== null);
+        if (focusable.length === 0) return;
+
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        if (!first || !last) return;
+        const active = document.activeElement as HTMLElement | null;
+
+        if (e.shiftKey && (active === first || !this.overlay.contains(active))) {
+          e.preventDefault();
+          last.focus({ preventScroll: true });
+        } else if (!e.shiftKey && active === last) {
+          e.preventDefault();
+          first.focus({ preventScroll: true });
+        }
+      }
+    };
+    const lifecycleSignal = (this.player as { lifecycleSignal?: AbortSignal }).lifecycleSignal;
+    document.addEventListener(
+      'keydown',
+      this._keydownHandler,
+      lifecycleSignal ? { signal: lifecycleSignal } : undefined
+    );
+
+    return overlay;
+  }
+
+  /**
+   * Whether a shortcut row is worth showing for *this* player. Feature actions
+   * are hidden when their control isn't present (e.g. no captions track, an
+   * audio-only player with no fullscreen). Core actions are always relevant.
+   *
+   * When the player has no control bar we can't infer availability, so nothing
+   * is hidden — the shortcuts still work and we'd rather over-show than mislead.
+   */
+  private isActionRelevant(action: keyof KeyboardShortcuts): boolean {
+    const requiredControl = ACTION_REQUIRES_CONTROL[action];
+    if (!requiredControl) return true;
+
+    const controlBar = (this.player as { controlBar?: { controls?: Record<string, unknown> } }).controlBar;
+    if (!controlBar || !controlBar.controls) return true;
+
+    return Boolean(controlBar.controls[requiredControl]);
+  }
+
+  private buildShortcutList(): HTMLElement {
+    const list = DOMUtils.createElement('dl', {
+      className: `${this.prefix}-help-list`
+    });
+
+    const shortcuts = this.player.options.keyboardShortcuts as unknown as Record<string, string[] | undefined>;
+
+    for (const action of ACTION_ORDER) {
+      const keys = shortcuts[action];
+      if (!Array.isArray(keys) || keys.length === 0) continue;
+      if (!this.isActionRelevant(action)) continue;
+
+      const term = DOMUtils.createElement('dt', {
+        className: `${this.prefix}-help-action`,
+        textContent: i18n.t(`help.actions.${action}`)
+      });
+
+      const desc = DOMUtils.createElement('dd', {
+        className: `${this.prefix}-help-keys`
+      });
+
+      keys.forEach((key, index) => {
+        if (index > 0) {
+          desc.appendChild(
+            DOMUtils.createElement('span', {
+              className: `${this.prefix}-help-key-sep`,
+              textContent: i18n.t('help.or')
+            })
+          );
+        }
+        desc.appendChild(
+          DOMUtils.createElement('kbd', {
+            className: `${this.prefix}-help-key`,
+            textContent: this.formatKey(key)
+          })
+        );
+      });
+
+      list.appendChild(term);
+      list.appendChild(desc);
+    }
+
+    return list;
+  }
+
+  show(): void {
+    if (this.isOpen) return;
+
+    if (!this.overlay) {
+      this.overlay = this.createElement();
+      this.player.container.appendChild(this.overlay);
+    } else if (this._content) {
+      // Rebuild so feature availability that changed since last open
+      // (e.g. HLS captions/qualities loaded later) is reflected.
+      this._content.replaceChildren(this.buildShortcutList());
+    }
+
+    const active = (typeof document !== 'undefined' ? document.activeElement : null) as HTMLElement | null;
+    this._triggerElement = active && typeof active.focus === 'function' ? active : null;
+
+    this.overlay.style.display = 'flex';
+    this.isOpen = true;
+
+    const closeButton = this.overlay.querySelector<HTMLElement>(`.${this.prefix}-settings-close`);
+    closeButton?.focus({ preventScroll: true });
+
+    this.player.emit('keyboardhelpopen');
+  }
+
+  hide(): void {
+    if (!this.overlay) return;
+
+    this.overlay.style.display = 'none';
+    this.isOpen = false;
+
+    const trigger = this._triggerElement;
+    this._triggerElement = null;
+    if (trigger && document.contains(trigger)) {
+      try {
+        trigger.focus({ preventScroll: true });
+      } catch {
+        this.player.container?.focus();
+      }
+    } else {
+      this.player.container?.focus();
+    }
+
+    this.player.emit('keyboardhelpclose');
+  }
+
+  toggle(): void {
+    if (this.isOpen) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+
+  destroy(): void {
+    if (this._keydownHandler) {
+      document.removeEventListener('keydown', this._keydownHandler);
+      this._keydownHandler = null;
+    }
+    if (this.overlay && this.overlay.parentNode) {
+      this.overlay.parentNode.removeChild(this.overlay);
+    }
+    this.overlay = null;
+    this._content = null;
+    this._triggerElement = null;
+    this.isOpen = false;
+  }
+}

package/src/controls/KeyboardManager.ts

@@ -269,6 +269,10 @@ export class KeyboardManager {
         }
         return false;
 
+      case 'help':
+        this.player.toggleKeyboardHelp();
+        return true;
+
       default:
         return false;
     }

package/src/core/MediaSessionManager.ts

@@ -0,0 +1,341 @@
+/**
+ * Media Session API integration.
+ *
+ * Wires the player into `navigator.mediaSession` so the OS shows
+ * now-playing metadata (title / artist / album / artwork) and routes
+ * hardware/lock-screen/notification controls (play, pause, stop, seek,
+ * and previous/next track for playlists) back into the player.
+ *
+ * Everything is feature-detected and wrapped in try/catch: unsupported
+ * browsers and unsupported individual actions degrade silently.
+ */
+
+import type { Player } from './Player.js';
+
+interface PlaylistLikeTrack {
+  title?: string;
+  artist?: string;
+  poster?: string;
+}
+
+const POSITION_THROTTLE_MS = 1000;
+
+/**
+ * `navigator.mediaSession` is a single, global object shared by the whole
+ * document, but a page can host several VidPly players at once (common in a
+ * CMS). Only one of them may own the session at a time, otherwise the OS
+ * controls would be wired to a player the user isn't actually listening to
+ * (clicking play/pause/next then appears to "do nothing").
+ *
+ * We track the owning manager here and follow the browser convention: the
+ * player that most recently started playing claims the session. Background
+ * players never touch the global session, and a player only releases it on
+ * destroy if it still owns it.
+ */
+let activeManager: MediaSessionManager | null = null;
+
+export class MediaSessionManager {
+  player: Player;
+  private supported: boolean;
+  private handlers: Partial<Record<string, () => void>> = {};
+  private boundActions: string[] = [];
+  private lastPositionUpdate = 0;
+
+  constructor(player: Player) {
+    this.player = player;
+    this.supported =
+      typeof navigator !== 'undefined' && 'mediaSession' in navigator;
+
+    if (!this.supported) return;
+
+    this.attachEvents();
+
+    // Claim the session up front only when no other player owns it yet (i.e.
+    // we're the first/only player on the page). When other players already
+    // exist we wait until this one actually starts playing before taking
+    // over, so we never hijack a player the user is currently using.
+    if (activeManager === null) {
+      this.claimSession();
+    }
+  }
+
+  /** Does this manager currently own the global media session? */
+  private isActive(): boolean {
+    return activeManager === this;
+  }
+
+  /**
+   * Take ownership of the global session: (re)register the action handlers so
+   * the OS controls drive this player, and refresh metadata/state/position.
+   */
+  private claimSession(): void {
+    if (!this.supported) return;
+    activeManager = this;
+    this.setupActionHandlers();
+    this.updateMetadata();
+    this.updatePlaybackState();
+    this.updatePositionState(true);
+  }
+
+  private get session(): MediaSession {
+    return navigator.mediaSession;
+  }
+
+  private setActionHandler(
+    action: MediaSessionAction,
+    handler: MediaSessionActionHandler | null
+  ): void {
+    try {
+      this.session.setActionHandler(action, handler);
+      if (handler && !this.boundActions.includes(action)) {
+        this.boundActions.push(action);
+      }
+    } catch {
+      // Action not supported by this browser - ignore.
+    }
+  }
+
+  private setupActionHandlers(): void {
+    this.setActionHandler('play', () => this.player.play());
+    this.setActionHandler('pause', () => this.player.pause());
+    this.setActionHandler('stop', () => this.player.stop());
+
+    this.setActionHandler('seekbackward', (details) => {
+      this.player.seekBackward(this.offsetFrom(details));
+    });
+    this.setActionHandler('seekforward', (details) => {
+      this.player.seekForward(this.offsetFrom(details));
+    });
+    this.setActionHandler('seekto', (details) => {
+      if (details && typeof details.seekTime === 'number') {
+        this.player.seek(details.seekTime);
+      }
+    });
+
+    this.updateTrackHandlers();
+  }
+
+  private offsetFrom(details?: MediaSessionActionDetails): number | undefined {
+    const offset = details && typeof details.seekOffset === 'number' ? details.seekOffset : undefined;
+    return typeof offset === 'number' && offset > 0 ? offset : undefined;
+  }
+
+  /**
+   * previous/next track only make sense with a multi-item playlist; bind
+   * or clear them whenever the playlist state changes so the OS shows the
+   * correct affordances.
+   */
+  private updateTrackHandlers(): void {
+    const pm = this.player.playlistManager;
+    const hasPlaylist = Boolean(pm && Array.isArray(pm.tracks) && pm.tracks.length > 1);
+
+    if (hasPlaylist && pm) {
+      this.setActionHandler('previoustrack', () => pm.previous());
+      this.setActionHandler('nexttrack', () => pm.next());
+    } else {
+      this.setActionHandler('previoustrack', null);
+      this.setActionHandler('nexttrack', null);
+    }
+  }
+
+  private attachEvents(): void {
+    this.handlers = {
+      // Starting playback makes this player the session owner, taking over
+      // the OS controls from any other player on the page.
+      play: () => this.claimSession(),
+      pause: () => {
+        if (!this.isActive()) return;
+        this.updatePlaybackState();
+        this.updatePositionState(true);
+      },
+      ended: () => {
+        if (!this.isActive()) return;
+        this.updatePlaybackState();
+      },
+      timeupdate: () => {
+        if (!this.isActive()) return;
+        this.updatePositionState();
+      },
+      durationchange: () => {
+        if (!this.isActive()) return;
+        this.updatePositionState(true);
+      },
+      ratechange: () => {
+        if (!this.isActive()) return;
+        this.updatePositionState(true);
+      },
+      loadedmetadata: () => {
+        if (!this.isActive()) return;
+        this.updateMetadata();
+        this.updatePositionState(true);
+      },
+      playlisttrackchange: () => {
+        if (!this.isActive()) return;
+        this.updateMetadata();
+        this.updateTrackHandlers();
+        this.updatePositionState(true);
+      }
+    };
+
+    for (const [event, handler] of Object.entries(this.handlers)) {
+      if (handler) {
+        this.player.on(event as never, handler as never);
+      }
+    }
+  }
+
+  private resolveMetadata(): {
+    title: string;
+    artist: string;
+    album: string;
+    poster: string | null;
+  } {
+    const opts = this.player.options;
+    let title = opts.title || '';
+    let artist = opts.artist || '';
+    const album = opts.album || '';
+    let poster = opts.poster || null;
+
+    const pm = this.player.playlistManager;
+    if (pm && Array.isArray(pm.tracks) && pm.currentIndex >= 0) {
+      const track = pm.tracks[pm.currentIndex] as PlaylistLikeTrack | undefined;
+      if (track) {
+        if (track.title) title = track.title;
+        if (track.artist) artist = track.artist;
+        if (track.poster) poster = track.poster;
+      }
+    }
+
+    if (!title && typeof document !== 'undefined') {
+      title = document.title || 'VidPly';
+    }
+
+    return { title, artist, album, poster };
+  }
+
+  updateMetadata(): void {
+    if (!this.supported || typeof window === 'undefined' || typeof window.MediaMetadata === 'undefined') {
+      return;
+    }
+
+    const { title, artist, album, poster } = this.resolveMetadata();
+    const artwork: MediaImage[] = [];
+
+    if (poster) {
+      try {
+        const src = this.player.resolvePosterPath(poster);
+        if (src) {
+          artwork.push({ src });
+        }
+      } catch {
+        // Ignore poster resolution failures.
+      }
+    }
+
+    try {
+      this.session.metadata = new window.MediaMetadata({
+        title,
+        artist,
+        album,
+        artwork
+      });
+    } catch {
+      // Ignore metadata construction failures.
+    }
+  }
+
+  updatePlaybackState(): void {
+    if (!this.supported) return;
+    try {
+      this.session.playbackState = this.player.state.playing ? 'playing' : 'paused';
+    } catch {
+      // Ignore.
+    }
+  }
+
+  /**
+   * Push the current position to the OS scrubber. `timeupdate` fires
+   * several times a second, so non-forced updates are throttled.
+   */
+  updatePositionState(force = false): void {
+    if (!this.supported || typeof this.session.setPositionState !== 'function') {
+      return;
+    }
+
+    const now = Date.now();
+    if (!force && now - this.lastPositionUpdate < POSITION_THROTTLE_MS) {
+      return;
+    }
+    this.lastPositionUpdate = now;
+
+    const duration = this.player.state.duration;
+    if (!Number.isFinite(duration) || duration <= 0) {
+      // A finite, positive duration is required; clear any stale state
+      // (e.g. live streams or before metadata is known).
+      try {
+        this.session.setPositionState();
+      } catch {
+        // Ignore.
+      }
+      return;
+    }
+
+    const playbackRate = this.player.state.playbackSpeed || 1;
+    const position = Math.min(Math.max(0, this.player.state.currentTime || 0), duration);
+
+    try {
+      this.session.setPositionState({
+        duration,
+        playbackRate: playbackRate > 0 ? playbackRate : 1,
+        position
+      });
+    } catch {
+      // Ignore (e.g. position > duration race).
+    }
+  }
+
+  destroy(): void {
+    if (!this.supported) return;
+
+    for (const [event, handler] of Object.entries(this.handlers)) {
+      if (handler) {
+        this.player.off(event as never, handler as never);
+      }
+    }
+    this.handlers = {};
+
+    // Only tear down the global session if we currently own it; otherwise we
+    // would wipe the controls of whichever player is actually playing.
+    if (this.isActive()) {
+      for (const action of this.boundActions) {
+        try {
+          this.session.setActionHandler(action as MediaSessionAction, null);
+        } catch {
+          // Ignore.
+        }
+      }
+
+      try {
+        this.session.metadata = null;
+      } catch {
+        // Ignore.
+      }
+      try {
+        if (typeof this.session.setPositionState === 'function') {
+          this.session.setPositionState();
+        }
+      } catch {
+        // Ignore.
+      }
+      try {
+        this.session.playbackState = 'none';
+      } catch {
+        // Ignore.
+      }
+
+      activeManager = null;
+    }
+
+    this.boundActions = [];
+  }
+}