@hanifhan1f/vidstack 1.12.13

package/src/components/ui/thumbnails/thumbnail-loader.ts

@@ -0,0 +1,324 @@
+import { effect, peek, signal, type ReadSignal } from 'maverick.js';
+import { isArray, isNumber, isObject, isString } from 'maverick.js/std';
+
+import { useMediaContext, type MediaContext } from '../../../core/api/media-context';
+import type { MediaCrossOrigin } from '../../../core/api/types';
+import { assert } from '../../../utils/error';
+import { getRequestCredentials } from '../../../utils/network';
+
+const cache = new Map<string, ThumbnailImage[]>(),
+  pending = new Map<string, Promise<ThumbnailImage[] | void>>(),
+  warned = __DEV__ ? new Set<ThumbnailSrc>() : undefined;
+
+export class ThumbnailsLoader {
+  readonly #media: MediaContext;
+  readonly #src: ReadSignal<ThumbnailSrc>;
+  readonly #crossOrigin: ReadSignal<MediaCrossOrigin | null>;
+
+  readonly $images = signal<ThumbnailImage[]>([]);
+
+  static create(src: ReadSignal<ThumbnailSrc>, crossOrigin: ReadSignal<MediaCrossOrigin | null>) {
+    const media = useMediaContext();
+    return new ThumbnailsLoader(src, crossOrigin, media);
+  }
+
+  constructor(
+    src: ReadSignal<ThumbnailSrc>,
+    crossOrigin: ReadSignal<MediaCrossOrigin | null>,
+    media: MediaContext,
+  ) {
+    this.#src = src;
+    this.#crossOrigin = crossOrigin;
+    this.#media = media;
+    effect(this.#onLoadCues.bind(this));
+  }
+
+  #onLoadCues() {
+    const { canLoad } = this.#media.$state;
+    if (!canLoad()) return;
+
+    const src = this.#src();
+    if (!src) return;
+
+    if (isString(src) && cache.has(src)) {
+      // Really basic LRU cache implementation.
+      const cues = cache.get(src)!;
+      cache.delete(src);
+      cache.set(src, cues);
+
+      if (cache.size > 99) {
+        const firstKey = cache.keys().next().value!;
+        cache.delete(firstKey);
+      }
+
+      this.$images.set(cache.get(src)!);
+    } else if (isString(src)) {
+      const crossOrigin = this.#crossOrigin(),
+        currentKey = src + '::' + crossOrigin;
+
+      if (!pending.has(currentKey)) {
+        const promise = new Promise<ThumbnailImage[]>(async (resolve, reject) => {
+          try {
+            const response = await fetch(src, {
+                credentials: getRequestCredentials(crossOrigin),
+              }),
+              isJSON = response.headers.get('content-type') === 'application/json';
+
+            if (isJSON) {
+              const json = await response.json();
+
+              if (isArray(json)) {
+                if (json[0] && 'text' in (json[0] as Partial<VTTCue>)) {
+                  resolve(this.#processVTTCues(json as any));
+                } else {
+                  for (let i = 0; i < json.length; i++) {
+                    const image = json[i];
+                    assert(isObject(image), __DEV__ && `Item not an object at index ${i}`);
+                    assert(
+                      'url' in image && isString(image.url),
+                      __DEV__ && `Invalid or missing \`url\` property at index ${i}`,
+                    );
+                    assert(
+                      'startTime' in image && isNumber(image.startTime),
+                      __DEV__ && `Invalid or missing \`startTime\` property at index ${i}`,
+                    );
+                  }
+
+                  resolve(json as ThumbnailImage[]);
+                }
+              } else {
+                resolve(this.#processStoryboard(json));
+              }
+
+              return;
+            }
+
+            import('media-captions').then(async ({ parseResponse }) => {
+              try {
+                const { cues } = await parseResponse(response);
+                resolve(this.#processVTTCues(cues));
+              } catch (e) {
+                reject(e);
+              }
+            });
+          } catch (e) {
+            reject(e);
+          }
+        })
+          .then((images) => {
+            cache.set(currentKey, images);
+            return images;
+          })
+          .catch((error) => {
+            this.#onError(src, error);
+          })
+          .finally(() => {
+            if (isString(currentKey)) pending.delete(currentKey);
+          });
+
+        pending.set(currentKey, promise);
+      }
+
+      pending.get(currentKey)?.then((images) => {
+        this.$images.set(images || []);
+      });
+    } else if (isArray(src)) {
+      try {
+        this.$images.set(this.#processImages(src));
+      } catch (error) {
+        this.#onError(src, error);
+      }
+    } else {
+      try {
+        this.$images.set(this.#processStoryboard(src));
+      } catch (error) {
+        this.#onError(src, error);
+      }
+    }
+
+    return () => {
+      this.$images.set([]);
+    };
+  }
+
+  #processImages(images: ThumbnailImageInit[]): ThumbnailImage[] {
+    const baseURL = this.#resolveBaseUrl();
+    return images.map((img, i) => {
+      assert(
+        img.url && isString(img.url),
+        __DEV__ && `Invalid or missing \`url\` property at index ${i}`,
+      );
+      assert(
+        'startTime' in img && isNumber(img.startTime),
+        __DEV__ && `Invalid or missing \`startTime\` property at index ${i}`,
+      );
+      return {
+        ...img,
+        url: isString(img.url) ? this.#resolveURL(img.url, baseURL) : img.url,
+      };
+    });
+  }
+
+  #processStoryboard(board: Partial<ThumbnailStoryboard> | Partial<MuxThumbnailStoryboard>) {
+    assert(isString(board.url), __DEV__ && 'Missing `url` in storyboard object');
+    assert(isArray(board.tiles) && board.tiles?.length, __DEV__ && `Empty tiles in storyboard`);
+
+    const url = new URL(board.url),
+      images: ThumbnailImage[] = [];
+
+    const tileWidth =
+        'tile_width' in board
+          ? board.tile_width
+          : (board as Partial<ThumbnailStoryboard>).tileWidth,
+      tileHeight =
+        'tile_height' in board
+          ? board.tile_height
+          : (board as Partial<ThumbnailStoryboard>).tileHeight;
+
+    for (const tile of board.tiles) {
+      images.push({
+        url,
+        startTime: 'start' in tile ? tile.start : tile.startTime,
+        width: tileWidth,
+        height: tileHeight,
+        coords: { x: tile.x, y: tile.y },
+      });
+    }
+
+    return images;
+  }
+
+  #processVTTCues(cues: { startTime?: number; endTime?: number; text?: string }[]) {
+    for (let i = 0; i < cues.length; i++) {
+      const cue = cues[i];
+      assert(
+        'startTime' in cue && isNumber(cue.startTime),
+        __DEV__ && `Invalid or missing \`startTime\` property at index ${i}`,
+      );
+      assert(
+        'text' in cue && isString(cue.text),
+        __DEV__ && `Invalid or missing \`text\` property at index ${i}`,
+      );
+    }
+
+    const images: ThumbnailImage[] = [],
+      baseURL = this.#resolveBaseUrl();
+
+    for (const cue of cues) {
+      const [url, hash] = cue.text!.split('#'),
+        data = this.#resolveData(hash);
+      images.push({
+        url: this.#resolveURL(url, baseURL),
+        startTime: cue.startTime!,
+        endTime: cue.endTime,
+        width: data?.w,
+        height: data?.h,
+        coords: data && isNumber(data.x) && isNumber(data.y) ? { x: data.x, y: data.y } : undefined,
+      });
+    }
+
+    return images;
+  }
+
+  #resolveBaseUrl() {
+    let baseURL = peek(this.#src);
+
+    if (!isString(baseURL) || !/^https?:/.test(baseURL)) {
+      return location.href;
+    }
+
+    return baseURL;
+  }
+
+  #resolveURL(src: string, baseURL: string) {
+    return /^https?:/.test(src) ? new URL(src) : new URL(src, baseURL);
+  }
+
+  #resolveData(hash?: string) {
+    if (!hash) return {};
+
+    // hash = xywh=0,0,256,160
+    const [hashProps, values] = hash.split('='),
+      hashValues = values?.split(','),
+      data: {
+        x?: number;
+        y?: number;
+        w?: number;
+        h?: number;
+      } = {};
+
+    if (!hashProps || !hashValues) {
+      return null;
+    }
+
+    for (let i = 0; i < hashProps.length; i++) {
+      const value = +hashValues[i];
+      if (!isNaN(value)) data[hashProps[i]] = value;
+    }
+
+    return data;
+  }
+
+  #onError(src: ThumbnailSrc, error: unknown) {
+    if (!__DEV__ || warned?.has(src)) return;
+
+    this.#media.logger
+      ?.errorGroup('[vidstack] failed to load thumbnails')
+      .labelledLog('Src', src)
+      .labelledLog('Error', error)
+      .dispatch();
+
+    warned?.add(src);
+  }
+}
+
+export type ThumbnailSrc =
+  | string
+  | ThumbnailImageInit[]
+  | ThumbnailStoryboard
+  | MuxThumbnailStoryboard
+  | null;
+
+export interface ThumbnailStoryboard {
+  url: string;
+  tileWidth: number;
+  tileHeight: number;
+  tiles: ThumbnailTile[];
+}
+
+export interface ThumbnailTile {
+  startTime: number;
+  x: number;
+  y: number;
+}
+
+export interface MuxThumbnailStoryboard {
+  url: string;
+  tile_width: number;
+  tile_height: number;
+  tiles: MuxThumbnailTile[];
+}
+
+export interface MuxThumbnailTile {
+  start: number;
+  x: number;
+  y: number;
+}
+
+export interface ThumbnailImageInit {
+  url: string | URL;
+  startTime: number;
+  endTime?: number;
+  width?: number;
+  height?: number;
+  coords?: ThumbnailCoords;
+}
+
+export interface ThumbnailImage extends Omit<ThumbnailImageInit, 'url'> {
+  url: URL;
+}
+
+export interface ThumbnailCoords {
+  x: number;
+  y: number;
+}

package/src/components/ui/thumbnails/thumbnail.ts

@@ -0,0 +1,244 @@
+import { Component, effect, State } from 'maverick.js';
+import { EventsController, isNull, listenEvent } from 'maverick.js/std';
+
+import { useMediaContext, type MediaContext } from '../../../core/api/media-context';
+import type { MediaCrossOrigin } from '../../../core/api/types';
+import { $ariaBool } from '../../../utils/aria';
+import { round } from '../../../utils/number';
+import { ThumbnailsLoader, type ThumbnailImage, type ThumbnailSrc } from './thumbnail-loader';
+
+/**
+ * Used to load and display a preview thumbnail at the given `time`.
+ *
+ * @attr data-loading - Whether thumbnail image is loading.
+ * @attr data-error - Whether an error occurred loading thumbnail.
+ * @attr data-hidden - Whether thumbnail is not available or failed to load.
+ * @docs {@link https://www.vidstack.io/docs/player/components/display/thumbnail}
+ */
+export class Thumbnail extends Component<ThumbnailProps, ThumbnailState> {
+  static props: ThumbnailProps = {
+    src: null,
+    time: 0,
+    crossOrigin: null,
+  };
+
+  static state = new State<ThumbnailState>({
+    src: '',
+    img: null,
+    thumbnails: [],
+    activeThumbnail: null,
+    crossOrigin: null,
+    loading: false,
+    error: null,
+    hidden: false,
+  });
+
+  protected media!: MediaContext;
+
+  #loader!: ThumbnailsLoader;
+  #styleResets: (() => void)[] = [];
+
+  protected override onSetup(): void {
+    this.media = useMediaContext();
+    this.#loader = ThumbnailsLoader.create(this.$props.src, this.$state.crossOrigin);
+
+    this.#watchCrossOrigin();
+
+    this.setAttributes({
+      'data-loading': this.#isLoading.bind(this),
+      'data-error': this.#hasError.bind(this),
+      'data-hidden': this.$state.hidden,
+      'aria-hidden': $ariaBool(this.$state.hidden),
+    });
+  }
+
+  protected override onConnect(el: HTMLElement) {
+    effect(this.#watchImg.bind(this));
+    effect(this.#watchHidden.bind(this));
+    effect(this.#watchCrossOrigin.bind(this));
+    effect(this.#onLoadStart.bind(this));
+    effect(this.#onFindActiveThumbnail.bind(this));
+    effect(this.#resize.bind(this));
+  }
+
+  #watchImg() {
+    const img = this.$state.img();
+
+    if (!img) return;
+
+    new EventsController(img)
+      .add('load', this.#onLoaded.bind(this))
+      .add('error', this.#onError.bind(this));
+  }
+
+  #watchCrossOrigin() {
+    const { crossOrigin: crossOriginProp } = this.$props,
+      { crossOrigin: crossOriginState } = this.$state,
+      { crossOrigin: mediaCrossOrigin } = this.media.$state,
+      crossOrigin = crossOriginProp() !== null ? crossOriginProp() : mediaCrossOrigin();
+    crossOriginState.set(crossOrigin === true ? 'anonymous' : crossOrigin);
+  }
+
+  #onLoadStart() {
+    const { src, loading, error } = this.$state;
+
+    if (src()) {
+      loading.set(true);
+      error.set(null);
+    }
+
+    return () => {
+      this.#resetStyles();
+      loading.set(false);
+      error.set(null);
+    };
+  }
+
+  #onLoaded() {
+    const { loading, error } = this.$state;
+    this.#resize();
+    loading.set(false);
+    error.set(null);
+  }
+
+  #onError(event: ErrorEvent) {
+    const { loading, error } = this.$state;
+    loading.set(false);
+    error.set(event);
+  }
+
+  #isLoading() {
+    const { loading, hidden } = this.$state;
+    return !hidden() && loading();
+  }
+
+  #hasError() {
+    const { error } = this.$state;
+    return !isNull(error());
+  }
+
+  #watchHidden() {
+    const { hidden } = this.$state,
+      { duration } = this.media.$state,
+      images = this.#loader.$images();
+    hidden.set(this.#hasError() || !Number.isFinite(duration()) || images.length === 0);
+  }
+
+  protected getTime() {
+    return this.$props.time();
+  }
+
+  #onFindActiveThumbnail() {
+    let images = this.#loader.$images();
+    if (!images.length) return;
+
+    let time = this.getTime(),
+      { src, activeThumbnail } = this.$state,
+      activeIndex = -1,
+      activeImage: ThumbnailImage | null = null;
+
+    for (let i = images.length - 1; i >= 0; i--) {
+      const image = images[i];
+      if (time >= image.startTime && (!image.endTime || time < image.endTime)) {
+        activeIndex = i;
+        break;
+      }
+    }
+
+    if (images[activeIndex]) {
+      activeImage = images[activeIndex];
+    }
+
+    activeThumbnail.set(activeImage);
+    src.set(activeImage?.url.href || '');
+  }
+
+  #resize() {
+    if (!this.scope || this.$state.hidden()) return;
+
+    const rootEl = this.el,
+      imgEl = this.$state.img(),
+      thumbnail = this.$state.activeThumbnail();
+
+    if (!imgEl || !thumbnail || !rootEl) return;
+
+    let width = thumbnail.width ?? imgEl.naturalWidth,
+      height = thumbnail?.height ?? imgEl.naturalHeight,
+      {
+        maxWidth,
+        maxHeight,
+        minWidth,
+        minHeight,
+        width: elWidth,
+        height: elHeight,
+      } = getComputedStyle(this.el);
+
+    if (minWidth === '100%') minWidth = parseFloat(elWidth) + '';
+    if (minHeight === '100%') minHeight = parseFloat(elHeight) + '';
+
+    let minRatio = Math.max(parseInt(minWidth) / width, parseInt(minHeight) / height),
+      maxRatio = Math.min(
+        Math.max(parseInt(minWidth), parseInt(maxWidth)) / width,
+        Math.max(parseInt(minHeight), parseInt(maxHeight)) / height,
+      ),
+      scale = !isNaN(maxRatio) && maxRatio < 1 ? maxRatio : minRatio > 1 ? minRatio : 1;
+
+    this.#style(rootEl, '--thumbnail-width', `${width * scale}px`);
+    this.#style(rootEl, '--thumbnail-height', `${height * scale}px`);
+    this.#style(rootEl, '--thumbnail-aspect-ratio', String(round(width / height, 5)));
+
+    this.#style(imgEl, 'width', `${imgEl.naturalWidth * scale}px`);
+    this.#style(imgEl, 'height', `${imgEl.naturalHeight * scale}px`);
+
+    this.#style(
+      imgEl,
+      'transform',
+      thumbnail.coords
+        ? `translate(-${thumbnail.coords.x * scale}px, -${thumbnail.coords.y * scale}px)`
+        : '',
+    );
+
+    this.#style(imgEl, 'max-width', 'none');
+  }
+
+  #style(el: HTMLElement, name: string, value: string) {
+    el.style.setProperty(name, value);
+    this.#styleResets.push(() => el.style.removeProperty(name));
+  }
+
+  #resetStyles() {
+    for (const reset of this.#styleResets) reset();
+    this.#styleResets = [];
+  }
+}
+
+export interface ThumbnailProps {
+  /**
+   * The thumbnails resource.
+   *
+   * @see {@link https://www.vidstack.io/docs/player/core-concepts/loading#thumbnails}
+   */
+  src: ThumbnailSrc;
+  /**
+   * Finds, loads, and displays the first active thumbnail cue that's start/end times are in range.
+   */
+  time: number;
+  /**
+   * Defines how the media handles cross-origin requests, thereby enabling the
+   * configuration of the CORS requests for the element's fetched data.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin}
+   */
+  crossOrigin: true | MediaCrossOrigin | null;
+}
+
+export interface ThumbnailState {
+  src: string;
+  img: HTMLImageElement | null | undefined;
+  crossOrigin: MediaCrossOrigin | null;
+  thumbnails: ThumbnailImage[];
+  activeThumbnail: ThumbnailImage | null;
+  loading: boolean;
+  error: ErrorEvent | null;
+  hidden: boolean;
+}