@hanifhan1f/vidstack 1.12.13

package/src/core/keyboard/controller.ts

@@ -0,0 +1,302 @@
+import { effect, peek, signal } from 'maverick.js';
+import { EventsController, isArray, isKeyboardClick, isString, listenEvent } from 'maverick.js/std';
+
+import { isHTMLMediaElement } from '../../providers/type-check';
+import type { MediaContext } from '../api/media-context';
+import { MediaPlayerController } from '../api/player-controller';
+import type { MediaKeyShortcuts } from './types';
+
+export const MEDIA_KEY_SHORTCUTS: MediaKeyShortcuts = {
+  togglePaused: 'k Space',
+  toggleMuted: 'm',
+  toggleFullscreen: 'f',
+  togglePictureInPicture: 'i',
+  toggleCaptions: 'c',
+  seekBackward: 'j J ArrowLeft',
+  seekForward: 'l L ArrowRight',
+  volumeUp: 'ArrowUp',
+  volumeDown: 'ArrowDown',
+  speedUp: '>',
+  slowDown: '<',
+};
+
+const MODIFIER_KEYS = new Set(['Shift', 'Alt', 'Meta', 'Ctrl']),
+  BUTTON_SELECTORS = 'button, [role="button"]',
+  IGNORE_SELECTORS =
+    'input, textarea, select, [contenteditable], [role^="menuitem"], [role="timer"]';
+
+export class MediaKeyboardController extends MediaPlayerController {
+  #media: MediaContext;
+
+  constructor(media: MediaContext) {
+    super();
+    this.#media = media;
+  }
+
+  protected override onConnect(): void {
+    effect(this.#onTargetChange.bind(this));
+  }
+
+  #onTargetChange() {
+    const { keyDisabled, keyTarget } = this.$props;
+    if (keyDisabled()) return;
+
+    const target = keyTarget() === 'player' ? this.el! : document,
+      $active = signal(false);
+
+    if (target === this.el) {
+      new EventsController(this.el)
+        .add('focusin', () => $active.set(true))
+        .add('focusout', (event) => {
+          if (!this.el!.contains(event.target as Node)) $active.set(false);
+        });
+    } else {
+      if (!peek($active)) $active.set(document.querySelector('[data-media-player]') === this.el);
+      listenEvent(document, 'focusin', (event) => {
+        const activePlayer = event
+          .composedPath()
+          .find((el) => el instanceof Element && el.localName === 'media-player');
+        if (activePlayer !== undefined) $active.set(this.el === activePlayer);
+      });
+    }
+
+    effect(() => {
+      if (!$active()) return;
+      new EventsController(target)
+        .add('keyup', this.#onKeyUp.bind(this))
+        .add('keydown', this.#onKeyDown.bind(this))
+        .add('keydown', this.#onPreventVideoKeys.bind(this), { capture: true });
+    });
+  }
+
+  #onKeyUp(event: KeyboardEvent) {
+    const focusedEl = document.activeElement;
+
+    if (!event.key || !this.$state.canSeek() || focusedEl?.matches(IGNORE_SELECTORS)) {
+      return;
+    }
+
+    let { method, value } = this.#getMatchingMethod(event);
+
+    if (!isString(value) && !isArray(value)) {
+      value?.onKeyUp?.({
+        event,
+        player: this.#media.player,
+        remote: this.#media.remote,
+      });
+
+      value?.callback?.(event, this.#media.remote);
+
+      return;
+    }
+
+    if (method?.startsWith('seek')) {
+      event.preventDefault();
+      event.stopPropagation();
+      if (this.#timeSlider) {
+        this.#forwardTimeKeyboardEvent(event, method === 'seekForward');
+        this.#timeSlider = null;
+      } else {
+        this.#media.remote.seek(this.#seekTotal!, event);
+        this.#seekTotal = undefined;
+      }
+    }
+
+    if (method?.startsWith('volume')) {
+      const volumeSlider = this.el!.querySelector('[data-media-volume-slider]');
+      volumeSlider?.dispatchEvent(
+        new KeyboardEvent('keyup', {
+          key: method === 'volumeUp' ? 'Up' : 'Down',
+          shiftKey: event.shiftKey,
+          trigger: event,
+        } as KeyboardEventInit),
+      );
+    }
+  }
+
+  #onKeyDown(event: KeyboardEvent) {
+    if (!event.key || MODIFIER_KEYS.has(event.key)) return;
+
+    const focusedEl = document.activeElement;
+
+    if (
+      focusedEl?.matches(IGNORE_SELECTORS) ||
+      (isKeyboardClick(event) && focusedEl?.matches(BUTTON_SELECTORS))
+    ) {
+      return;
+    }
+
+    let { method, value } = this.#getMatchingMethod(event),
+      isNumberPress = !event.metaKey && /^[0-9]$/.test(event.key);
+
+    if (!isString(value) && !isArray(value) && !isNumberPress) {
+      value?.onKeyDown?.({
+        event,
+        player: this.#media.player,
+        remote: this.#media.remote,
+      });
+
+      value?.callback?.(event, this.#media.remote);
+
+      return;
+    }
+
+    if (!method && isNumberPress && !modifierKeyPressed(event)) {
+      event.preventDefault();
+      event.stopPropagation();
+      this.#media.remote.seek((this.$state.duration() / 10) * Number(event.key), event);
+      return;
+    }
+
+    if (!method) return;
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    switch (method) {
+      case 'seekForward':
+      case 'seekBackward':
+        this.#seeking(event, method, method === 'seekForward');
+        break;
+      case 'volumeUp':
+      case 'volumeDown':
+        const volumeSlider = this.el!.querySelector('[data-media-volume-slider]');
+        if (volumeSlider) {
+          volumeSlider.dispatchEvent(
+            new KeyboardEvent('keydown', {
+              key: method === 'volumeUp' ? 'Up' : 'Down',
+              shiftKey: event.shiftKey,
+              trigger: event,
+            } as KeyboardEventInit),
+          );
+        } else {
+          const value = event.shiftKey ? 0.1 : 0.05;
+          this.#media.remote.changeVolume(
+            this.$state.volume() + (method === 'volumeUp' ? +value : -value),
+            event,
+          );
+        }
+        break;
+      case 'toggleFullscreen':
+        this.#media.remote.toggleFullscreen('prefer-media', event);
+        break;
+      case 'speedUp':
+      case 'slowDown':
+        const playbackRate = this.$state.playbackRate();
+        this.#media.remote.changePlaybackRate(
+          Math.max(0.25, Math.min(2, playbackRate + (method === 'speedUp' ? 0.25 : -0.25))),
+          event,
+        );
+        break;
+      default:
+        this.#media.remote[method]?.(event);
+    }
+
+    this.$state.lastKeyboardAction.set({
+      action: method,
+      event,
+    });
+  }
+
+  #onPreventVideoKeys(event: KeyboardEvent) {
+    if (isHTMLMediaElement(event.target) && this.#getMatchingMethod(event).method) {
+      event.preventDefault();
+    }
+  }
+
+  #getMatchingMethod(event: KeyboardEvent) {
+    const keyShortcuts = {
+      ...this.$props.keyShortcuts(),
+      ...this.#media.ariaKeys,
+    };
+
+    const method = Object.keys(keyShortcuts).find((method) => {
+      const value = keyShortcuts[method as keyof typeof keyShortcuts],
+        keys = isArray(value) ? value.join(' ') : isString(value) ? value : value?.keys;
+
+      const combinations = (isArray(keys) ? keys : keys?.split(' '))?.map((key) =>
+        replaceSymbolKeys(key)
+          .replace(/Control/g, 'Ctrl')
+          .split('+'),
+      );
+
+      return combinations?.some((combo) => {
+        const modifierKeys = new Set(combo.filter((key) => MODIFIER_KEYS.has(key)));
+        if ('<>'.includes(event.key)) {
+          modifierKeys.add('Shift');
+        }
+
+        // Check whether a modifier key was pressed that's not part of this combination.
+        for (const modKey of MODIFIER_KEYS) {
+          const modKeyProp = modKey.toLowerCase() + 'Key';
+          if (!modifierKeys.has(modKey) && event[modKeyProp]) {
+            return false;
+          }
+        }
+
+        return combo.every((key) => {
+          return MODIFIER_KEYS.has(key)
+            ? event[key.toLowerCase() + 'Key']
+            : event.key === key.replace('Space', ' ');
+        });
+      });
+    });
+
+    return {
+      method,
+      value: method ? keyShortcuts[method] : null,
+    };
+  }
+
+  #seekTotal: number | undefined;
+  #calcSeekAmount(event: KeyboardEvent, type: string) {
+    const seekBy = event.shiftKey ? 10 : 5;
+    return (this.#seekTotal = Math.max(
+      0,
+      Math.min(
+        (this.#seekTotal ?? this.$state.currentTime()) +
+          (type === 'seekForward' ? +seekBy : -seekBy),
+        this.$state.duration(),
+      ),
+    ));
+  }
+
+  #timeSlider: Element | null = null;
+  #forwardTimeKeyboardEvent(event: KeyboardEvent, forward: boolean) {
+    this.#timeSlider?.dispatchEvent(
+      new KeyboardEvent(event.type, {
+        key: !forward ? 'Left' : 'Right',
+        shiftKey: event.shiftKey,
+        trigger: event,
+      } as KeyboardEventInit),
+    );
+  }
+
+  #seeking(event: KeyboardEvent, type: string, forward: boolean) {
+    if (!this.$state.canSeek()) return;
+
+    if (!this.#timeSlider) {
+      this.#timeSlider = this.el!.querySelector('[data-media-time-slider]');
+    }
+
+    if (this.#timeSlider) {
+      this.#forwardTimeKeyboardEvent(event, forward);
+    } else {
+      this.#media.remote.seeking(this.#calcSeekAmount(event, type), event);
+    }
+  }
+}
+
+const SYMBOL_KEY_MAP = ['!', '@', '#', '$', '%', '^', '&', '*', '(', ')'];
+function replaceSymbolKeys(key: string) {
+  return key.replace(/Shift\+(\d)/g, (_, num) => SYMBOL_KEY_MAP[num - 1]);
+}
+
+function modifierKeyPressed(event: KeyboardEvent) {
+  for (const key of MODIFIER_KEYS) {
+    if (event[key.toLowerCase() + 'Key']) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/core/keyboard/types.ts

@@ -0,0 +1,40 @@
+import type { MediaPlayer } from '../../components/player';
+import type { MediaRemoteControl } from '../state/remote-control';
+
+export type MediaKeyTarget = 'document' | 'player';
+
+export interface MediaKeyShortcuts {
+  [keys: string]: MediaKeyShortcut | undefined;
+  togglePaused?: MediaKeyShortcut;
+  toggleMuted?: MediaKeyShortcut;
+  toggleFullscreen?: MediaKeyShortcut;
+  togglePictureInPicture?: MediaKeyShortcut;
+  toggleCaptions?: MediaKeyShortcut;
+  seekBackward?: MediaKeyShortcut;
+  seekForward?: MediaKeyShortcut;
+  speedUp?: MediaKeyShortcut;
+  slowDown?: MediaKeyShortcut;
+  volumeUp?: MediaKeyShortcut;
+  volumeDown?: MediaKeyShortcut;
+}
+
+export type MediaKeyShortcut = MediaKeysCallback | string | string[] | null;
+
+export interface MediaKeysCallback {
+  keys: string | string[];
+
+  /** @deprecated - use `onKeyUp` or `onKeyDown` */
+  callback?(event: KeyboardEvent, remote: MediaRemoteControl): void;
+
+  onKeyUp?(context: {
+    event: KeyboardEvent;
+    player: MediaPlayer;
+    remote: MediaRemoteControl;
+  }): void;
+
+  onKeyDown?(context: {
+    event: KeyboardEvent;
+    player: MediaPlayer;
+    remote: MediaRemoteControl;
+  }): void;
+}

package/src/core/quality/events.ts

@@ -0,0 +1,48 @@
+import type { DOMEvent } from 'maverick.js/std';
+
+import type { ListReadonlyChangeEvent } from '../../foundation/list/list';
+import type { VideoQuality, VideoQualityList } from './video-quality';
+
+export interface VideoQualityListEvents {
+  add: VideoQualityAddEvent;
+  remove: VideoQualityRemoveEvent;
+  change: VideoQualityChangeEvent;
+  'auto-change': VideoQualityAutoChangeEvent;
+  'readonly-change': ListReadonlyChangeEvent;
+}
+
+export interface VideoQualityListEvent<T> extends DOMEvent<T> {
+  target: VideoQualityList;
+}
+
+/**
+ * Fired when a video quality has been added to the list.
+ *
+ * @detail newQuality
+ */
+export interface VideoQualityAddEvent extends VideoQualityListEvent<VideoQuality> {}
+
+/**
+ * Fired when a video quality has been removed from the list.
+ *
+ * @detail removedQuality
+ */
+export interface VideoQualityRemoveEvent extends VideoQualityListEvent<VideoQuality> {}
+
+/**
+ * Fired when the selected video quality has changed.
+ *
+ * @detail change
+ */
+export interface VideoQualityChangeEvent
+  extends VideoQualityListEvent<VideoQualityChangeEventDetail> {}
+
+export interface VideoQualityChangeEventDetail {
+  prev: VideoQuality | null;
+  current: VideoQuality;
+}
+
+/**
+ * Fired when auto quality selection is enabled or disabled.
+ */
+export interface VideoQualityAutoChangeEvent extends VideoQualityListEvent<boolean> {}

package/src/core/quality/symbols.ts

@@ -0,0 +1,8 @@
+export const SET_AUTO = Symbol(__DEV__ ? 'SET_AUTO_QUALITY' : 0),
+  ENABLE_AUTO = Symbol(__DEV__ ? 'ENABLE_AUTO_QUALITY' : 0);
+
+/** @internal */
+export const QualitySymbol = {
+  setAuto: SET_AUTO,
+  enableAuto: ENABLE_AUTO,
+} as const;

package/src/core/quality/utils.ts

@@ -0,0 +1,13 @@
+import type { VideoQuality } from './video-quality';
+
+export function sortVideoQualities(qualities: VideoQuality[], desc?: boolean) {
+  return [...qualities].sort(desc ? compareVideoQualityDesc : compareVideoQualityAsc);
+}
+
+function compareVideoQualityAsc(a: VideoQuality, b: VideoQuality) {
+  return a.height === b.height ? (a.bitrate ?? 0) - (b.bitrate ?? 0) : a.height - b.height;
+}
+
+function compareVideoQualityDesc(a: VideoQuality, b: VideoQuality) {
+  return b.height === a.height ? (b.bitrate ?? 0) - (a.bitrate ?? 0) : b.height - a.height;
+}

package/src/core/quality/video-quality.ts

@@ -0,0 +1,86 @@
+import { DOMEvent } from 'maverick.js/std';
+
+import { SelectList, type SelectListItem } from '../../foundation/list/select-list';
+import { ListSymbol } from '../../foundation/list/symbols';
+import type { VideoQualityListEvents } from './events';
+import { QualitySymbol } from './symbols';
+
+/**
+ * @see {@link https://vidstack.io/docs/player/core-concepts/video-quality#quality-list}
+ */
+export class VideoQualityList extends SelectList<VideoQuality, VideoQualityListEvents> {
+  #auto = false;
+
+  /**
+   * Configures quality switching:
+   *
+   * - `current`: Trigger an immediate quality level switch. This will abort the current fragment
+   * request if any, flush the whole buffer, and fetch fragment matching with current position
+   * and requested quality level.
+   *
+   * - `next`: Trigger a quality level switch for next fragment. This could eventually flush
+   * already buffered next fragment.
+   *
+   * - `load`: Set quality level for next loaded fragment.
+   *
+   * @see {@link https://www.vidstack.io/docs/player/api/video-quality#switch}
+   * @see {@link https://github.com/video-dev/hls.js/blob/master/docs/API.md#quality-switch-control-api}
+   */
+  switch: 'current' | 'next' | 'load' = 'current';
+
+  /**
+   * Whether automatic quality selection is enabled.
+   */
+  get auto() {
+    return this.#auto || this.readonly;
+  }
+
+  /** @internal */
+  [QualitySymbol.enableAuto]?: (trigger?: Event) => void;
+
+  /** @internal */
+  protected override [ListSymbol.onUserSelect]() {
+    this[QualitySymbol.setAuto](false);
+  }
+
+  /** @internal */
+  protected override [ListSymbol.onReset](trigger?: Event) {
+    this[QualitySymbol.enableAuto] = undefined;
+    this[QualitySymbol.setAuto](false, trigger);
+  }
+
+  /**
+   * Request automatic quality selection (if supported). This will be a no-op if the list is
+   * `readonly` as that already implies auto-selection.
+   */
+  autoSelect(trigger?: Event): void {
+    if (this.readonly || this.#auto || !this[QualitySymbol.enableAuto]) return;
+    this[QualitySymbol.enableAuto]?.(trigger);
+    this[QualitySymbol.setAuto](true, trigger);
+  }
+
+  getBySrc(src: unknown) {
+    return this.items.find((quality) => quality.src === src);
+  }
+
+  /** @internal */
+  [QualitySymbol.setAuto](auto: boolean, trigger?: Event) {
+    if (this.#auto === auto) return;
+    this.#auto = auto;
+    this.dispatchEvent(
+      new DOMEvent<any>('auto-change', {
+        detail: auto,
+        trigger,
+      }),
+    );
+  }
+}
+
+export interface VideoQuality extends SelectListItem {
+  readonly id: string;
+  readonly src?: unknown;
+  readonly width: number;
+  readonly height: number;
+  readonly bitrate: number | null;
+  readonly codec: string | null;
+}

package/src/core/state/media-events-logger.ts

@@ -0,0 +1,67 @@
+import { EventsController } from 'maverick.js/std';
+
+import { type MediaContext } from '../api/media-context';
+import type { MediaEvents } from '../api/media-events';
+import { MediaPlayerController } from '../api/player-controller';
+
+const MEDIA_EVENTS: (keyof MediaEvents)[] | undefined = __DEV__
+  ? [
+      'abort',
+      'can-play',
+      'can-play-through',
+      'duration-change',
+      'emptied',
+      'ended',
+      'error',
+      'fullscreen-change',
+      'loaded-data',
+      'loaded-metadata',
+      'load-start',
+      'media-type-change',
+      'pause',
+      'play',
+      'playing',
+      'progress',
+      'seeked',
+      'seeking',
+      'source-change',
+      'sources-change',
+      'stalled',
+      'started',
+      'suspend',
+      'stream-type-change',
+      'replay',
+      // time-change,
+      // 'time-update',
+      'view-type-change',
+      'volume-change',
+      'waiting',
+    ]
+  : undefined;
+
+export class MediaEventsLogger extends MediaPlayerController {
+  #media: MediaContext;
+
+  constructor(media: MediaContext) {
+    super();
+    this.#media = media;
+  }
+
+  protected override onConnect(el: HTMLElement): void {
+    const events = new EventsController(el),
+      handler = this.#onMediaEvent.bind(this);
+
+    for (const eventType of MEDIA_EVENTS!) {
+      // @ts-expect-error - player events on html element
+      events.add(eventType, handler);
+    }
+  }
+
+  #onMediaEvent(event: Event) {
+    this.#media.logger
+      ?.debugGroup(`📡 dispatching \`${event.type}\``)
+      .labelledLog('Media Store', { ...this.$state })
+      .labelledLog('Event', event)
+      .dispatch();
+  }
+}

package/src/core/state/media-load-controller.ts

@@ -0,0 +1,40 @@
+import { onDispose } from 'maverick.js';
+import { waitIdlePeriod } from 'maverick.js/std';
+
+import { MediaPlayerController } from '../api/player-controller';
+
+export class MediaLoadController extends MediaPlayerController {
+  #type: 'load' | 'posterLoad';
+  #callback: () => void;
+
+  constructor(type: 'load' | 'posterLoad', callback: () => void) {
+    super();
+    this.#type = type;
+    this.#callback = callback;
+  }
+
+  override async onAttach(el: HTMLElement) {
+    if (__SERVER__) return;
+
+    const load = this.$props[this.#type]();
+
+    if (load === 'eager') {
+      requestAnimationFrame(this.#callback);
+    } else if (load === 'idle') {
+      waitIdlePeriod(this.#callback);
+    } else if (load === 'visible') {
+      let dispose: (() => void) | undefined,
+        observer = new IntersectionObserver((entries) => {
+          if (!this.scope) return;
+          if (entries[0].isIntersecting) {
+            dispose?.();
+            dispose = undefined;
+            this.#callback();
+          }
+        });
+
+      observer.observe(el);
+      dispose = onDispose(() => observer.disconnect());
+    }
+  }
+}