@hanifhan1f/vidstack-react 1.12.13

package/src/hooks/options/use-video-quality-options.ts

@@ -0,0 +1,123 @@
+import * as React from 'react';
+
+import { useSignal } from 'maverick.js/react';
+import { isString } from 'maverick.js/std';
+import { sortVideoQualities, type VideoQuality } from 'vidstack';
+
+import { useMediaContext } from '../use-media-context';
+
+/**
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-video-quality-options}
+ */
+export function useVideoQualityOptions({
+  auto = true,
+  sort = 'descending',
+}: UseVideoQualityOptions = {}): VideoQualityOptions {
+  const media = useMediaContext(),
+    { qualities, quality, autoQuality, canSetQuality } = media.$state,
+    $qualities = useSignal(qualities);
+
+  // Trigger updates.
+  useSignal(quality);
+  useSignal(autoQuality);
+  useSignal(canSetQuality);
+
+  return React.useMemo(() => {
+    const sortedQualities = sortVideoQualities($qualities, sort === 'descending'),
+      options = sortedQualities.map<VideoQualityOption>((q) => {
+        return {
+          quality: q,
+          label: q.height + 'p',
+          value: getQualityValue(q),
+          bitrateText:
+            q.bitrate && q.bitrate > 0 ? `${(q.bitrate / 1000000).toFixed(2)} Mbps` : null,
+          get selected() {
+            return q === quality();
+          },
+          get autoSelected() {
+            return autoQuality();
+          },
+          select(trigger) {
+            const index = qualities().indexOf(q);
+            if (index >= 0) media.remote.changeQuality(index, trigger);
+          },
+        };
+      });
+
+    if (auto) {
+      options.unshift({
+        quality: null,
+        label: isString(auto) ? auto : 'Auto',
+        value: 'auto',
+        bitrateText: null,
+        get selected() {
+          return autoQuality();
+        },
+        get autoSelected() {
+          return autoQuality();
+        },
+        select(trigger) {
+          media.remote.requestAutoQuality(trigger);
+        },
+      });
+    }
+
+    Object.defineProperty(options, 'disabled', {
+      get() {
+        return !canSetQuality() || $qualities.length <= 1;
+      },
+    });
+
+    Object.defineProperty(options, 'selectedQuality', {
+      get() {
+        return quality();
+      },
+    });
+
+    Object.defineProperty(options, 'selectedValue', {
+      get() {
+        const $quality = quality();
+        return !autoQuality() && $quality ? getQualityValue($quality) : 'auto';
+      },
+    });
+
+    return options as VideoQualityOptions;
+  }, [$qualities, sort]);
+}
+
+export interface UseVideoQualityOptions {
+  /**
+   * Whether an auto option should be included. A string can be provided to specify the label.
+   */
+  auto?: boolean | string;
+  /**
+   * Specifies how the options should be sorted. The sorting algorithm looks at both the quality
+   * resolution and bitrate.
+   *
+   * - Ascending: 480p, 720p, 720p (higher bitrate), 1080p
+   * - Descending: 1080p, 720p (higher bitrate), 720p, 480p
+   *
+   * @default 'descending'
+   */
+  sort?: 'ascending' | 'descending';
+}
+
+export type VideoQualityOptions = VideoQualityOption[] & {
+  readonly disabled: boolean;
+  readonly selectedQuality: VideoQuality | null;
+  readonly selectedValue: string;
+};
+
+export interface VideoQualityOption {
+  readonly quality: VideoQuality | null;
+  readonly label: string;
+  readonly value: string;
+  readonly selected: boolean;
+  readonly autoSelected: boolean;
+  readonly bitrateText: string | null;
+  select(trigger?: Event): void;
+}
+
+function getQualityValue(quality: VideoQuality) {
+  return quality.height + '_' + quality.bitrate;
+}

package/src/hooks/use-active-text-cues.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+import { listenEvent } from 'maverick.js/std';
+import type { VTTCue } from 'media-captions';
+import type { TextTrack } from 'vidstack';
+
+/**
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-active-text-cues}
+ */
+export function useActiveTextCues(track: TextTrack | null): VTTCue[] {
+  const [activeCues, setActiveCues] = React.useState<VTTCue[]>([]);
+
+  React.useEffect(() => {
+    if (!track) {
+      setActiveCues([]);
+      return;
+    }
+
+    function onCuesChange() {
+      if (track) setActiveCues(track.activeCues as VTTCue[]);
+    }
+
+    onCuesChange();
+    return listenEvent(track, 'cue-change', onCuesChange);
+  }, [track]);
+
+  return activeCues;
+}

package/src/hooks/use-active-text-track.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+
+import { watchActiveTextTrack, type TextTrack } from 'vidstack';
+
+import { useMediaContext } from './use-media-context';
+
+/**
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-active-text-track}
+ */
+export function useActiveTextTrack(kind: TextTrackKind | TextTrackKind[]): TextTrack | null {
+  const media = useMediaContext(),
+    [track, setTrack] = React.useState<TextTrack | null>(null);
+
+  React.useEffect(() => {
+    return watchActiveTextTrack(media.textTracks, kind, setTrack);
+  }, [kind]);
+
+  return track;
+}

package/src/hooks/use-chapter-title.ts

@@ -0,0 +1,12 @@
+import { useActiveTextCues } from './use-active-text-cues';
+import { useActiveTextTrack } from './use-active-text-track';
+
+/**
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-chapter-title}
+ */
+export function useChapterTitle(): string {
+  const $track = useActiveTextTrack('chapters'),
+    $cues = useActiveTextCues($track);
+
+  return $cues[0]?.text || '';
+}

package/src/hooks/use-dom.ts

@@ -0,0 +1,121 @@
+import * as React from 'react';
+
+import { animationFrameThrottle, EventsController, listenEvent, setStyle } from 'maverick.js/std';
+
+export function useClassName(el: HTMLElement | null, className?: string) {
+  React.useEffect(() => {
+    if (!el || !className) return;
+
+    const tokens = className.split(' ');
+    for (const token of tokens) el.classList.add(token);
+
+    return () => {
+      for (const token of tokens) el.classList.remove(token);
+    };
+  }, [el, className]);
+}
+
+export function useResizeObserver(el: Element | null | undefined, callback: () => void) {
+  React.useEffect(() => {
+    if (!el) return;
+
+    callback();
+
+    const observer = new ResizeObserver(animationFrameThrottle(callback));
+    observer.observe(el);
+
+    return () => observer.disconnect();
+  }, [el, callback]);
+}
+
+export function useTransitionActive(el: Element | null) {
+  const [isActive, setIsActive] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!el) return;
+
+    const events = new EventsController(el)
+      .add('transitionstart', () => setIsActive(true))
+      .add('transitionend', () => setIsActive(false));
+
+    return () => events.abort();
+  }, [el]);
+
+  return isActive;
+}
+
+export function useMouseEnter(el: Element | null) {
+  const [isMouseEnter, setIsMouseEnter] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!el) return;
+
+    const events = new EventsController(el)
+      .add('mouseenter', () => setIsMouseEnter(true))
+      .add('mouseleave', () => setIsMouseEnter(false));
+
+    return () => events.abort();
+  }, [el]);
+
+  return isMouseEnter;
+}
+
+export function useFocusIn(el: Element | null) {
+  const [isFocusIn, setIsFocusIn] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!el) return;
+
+    const events = new EventsController(el)
+      .add('focusin', () => setIsFocusIn(true))
+      .add('focusout', () => setIsFocusIn(false));
+
+    return () => events.abort();
+  }, [el]);
+
+  return isFocusIn;
+}
+
+export function useActive(el: Element | null) {
+  const isMouseEnter = useMouseEnter(el),
+    isFocusIn = useFocusIn(el),
+    prevMouseEnter = React.useRef(false);
+
+  if (prevMouseEnter.current && !isMouseEnter) return false;
+
+  prevMouseEnter.current = isMouseEnter;
+  return isMouseEnter || isFocusIn;
+}
+
+export function useRectCSSVars(root: Element | null, el: Element | null, prefix: string) {
+  const onResize = React.useCallback(() => {
+    if (root && el) setRectCSSVars(root, el, prefix);
+  }, [root, el, prefix]);
+
+  useResizeObserver(el, onResize);
+}
+
+export function setRectCSSVars(root: Element, el: Element, prefix: string) {
+  const rect = el.getBoundingClientRect();
+  for (const side of ['top', 'left', 'bottom', 'right']) {
+    setStyle(root as HTMLElement, `--${prefix}-${side}`, `${rect[side]}px`);
+  }
+}
+
+export function useColorSchemePreference() {
+  const [colorScheme, setColorScheme] = React.useState<'light' | 'dark'>('dark');
+
+  React.useEffect(() => {
+    const media = window.matchMedia('(prefers-color-scheme: light)');
+
+    function onChange() {
+      setColorScheme(media.matches ? 'light' : 'dark');
+    }
+
+    onChange();
+
+    return listenEvent(media, 'change', onChange);
+  }, []);
+
+  return colorScheme;
+}

package/src/hooks/use-media-context.ts

@@ -0,0 +1,6 @@
+import { useReactContext } from 'maverick.js/react';
+import { mediaContext } from 'vidstack';
+
+export function useMediaContext() {
+  return useReactContext(mediaContext)!;
+}

package/src/hooks/use-media-player.ts

@@ -0,0 +1,19 @@
+import type { MediaPlayerInstance } from '../components/primitives/instances';
+import { useMediaContext } from './use-media-context';
+
+/**
+ * Returns the nearest parent player component.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-media-player}
+ */
+export function useMediaPlayer(): MediaPlayerInstance | null {
+  const context = useMediaContext();
+
+  if (__DEV__ && !context) {
+    throw Error(
+      '[vidstack] no media context was found - was this called outside of `<MediaPlayer>`?',
+    );
+  }
+
+  return context?.player || null;
+}

package/src/hooks/use-media-provider.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+
+import { effect } from 'maverick.js';
+import { type MediaProviderAdapter } from 'vidstack';
+
+import { useMediaContext } from './use-media-context';
+
+/**
+ * Returns the current parent media provider.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-media-provider}
+ */
+export function useMediaProvider(): MediaProviderAdapter | null {
+  const [provider, setProvider] = React.useState<MediaProviderAdapter | null>(null),
+    context = useMediaContext();
+
+  if (__DEV__ && !context) {
+    throw Error(
+      '[vidstack] no media context was found - was this called outside of `<MediaPlayer>`?',
+    );
+  }
+
+  React.useEffect(() => {
+    if (!context) return;
+    return effect(() => {
+      setProvider(context.$provider());
+    });
+  }, []);
+
+  return provider;
+}

package/src/hooks/use-media-remote.ts

@@ -0,0 +1,37 @@
+import * as React from 'react';
+
+import { MediaRemoteControl } from 'vidstack';
+
+import { MediaPlayerInstance } from '../components/primitives/instances';
+import { useMediaContext } from './use-media-context';
+
+/**
+ * A media remote provides a simple facade for dispatching media requests to the nearest media
+ * player.
+ *
+ * @param target - The DOM event target to dispatch request events from. Defaults to player
+ * if no target is provided.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-media-remote}
+ */
+export function useMediaRemote(
+  target?: EventTarget | null | React.RefObject<EventTarget | null>,
+): MediaRemoteControl {
+  const media = useMediaContext(),
+    remote = React.useRef<MediaRemoteControl>(null!);
+
+  if (!remote.current) {
+    remote.current = new MediaRemoteControl();
+  }
+
+  React.useEffect(() => {
+    const ref = target && 'current' in target ? target.current : target,
+      isPlayerRef = ref instanceof MediaPlayerInstance,
+      player = isPlayerRef ? ref : media?.player;
+
+    remote.current!.setPlayer(player ?? null);
+    remote.current!.setTarget(ref ?? null);
+  }, [media, target && 'current' in target ? target.current : target]);
+
+  return remote.current;
+}

package/src/hooks/use-media-state.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+
+import { useSignal, useSignalRecord, useStateContext } from 'maverick.js/react';
+import { mediaState, type MediaState } from 'vidstack';
+
+import { MediaPlayerInstance } from '../components/primitives/instances';
+
+const mediaStateRecord = MediaPlayerInstance.state.record,
+  initialMediaStore = Object.keys(mediaStateRecord).reduce(
+    (store, prop) => ({
+      ...store,
+      [prop]() {
+        return mediaStateRecord[prop];
+      },
+    }),
+    {},
+  );
+
+/**
+ * This hook is used to subscribe to a specific media state.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-media-state}
+ */
+export function useMediaState<T extends keyof MediaState>(
+  prop: T,
+  ref?: React.RefObject<MediaPlayerInstance | null>,
+): MediaState[T] {
+  const $state = useStateContext(mediaState);
+
+  if (__DEV__ && !$state && !ref) {
+    console.warn(
+      `[vidstack] \`useMediaState\` requires \`RefObject<MediaPlayerInstance>\` argument if called` +
+        ' outside the `<MediaPlayer>` component',
+    );
+  }
+
+  return useSignal((ref?.current?.$state || $state || initialMediaStore)[prop]);
+}
+
+/**
+ * This hook is used to subscribe to the current media state on the nearest parent player.
+ *
+ * @docs {@link https://vidstack.io/docs/player/core-concepts/state-management#reading}
+ */
+export function useMediaStore(
+  ref?: React.RefObject<MediaPlayerInstance | null>,
+): Readonly<MediaState> {
+  const $state = useStateContext(mediaState);
+
+  if (__DEV__ && !$state && !ref) {
+    console.warn(
+      `[vidstack] \`useMediaStore\` requires \`RefObject<MediaPlayerInstance>\` argument if called` +
+        ' outside the `<MediaPlayer>` component',
+    );
+  }
+
+  return useSignalRecord(ref?.current ? ref.current.$state : $state || initialMediaStore);
+}

package/src/hooks/use-signals.ts

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+import { computed, effect, scoped, signal, type MaybeStopEffect } from 'maverick.js';
+import { useReactScope } from 'maverick.js/react';
+
+export function createSignal<T>(initialValue: T, deps: any[] = []) {
+  const scope = useReactScope();
+  return React.useMemo(() => scoped(() => signal(initialValue), scope)!, [scope, ...deps]);
+}
+
+export function createComputed<T>(compute: () => T, deps: any[] = []) {
+  const scope = useReactScope();
+  return React.useMemo(() => scoped(() => computed(compute), scope)!, [scope, ...deps]);
+}
+
+export function createEffect(compute: () => MaybeStopEffect, deps: any[] = []) {
+  const scope = useReactScope();
+  React.useEffect(() => scoped(() => effect(compute), scope)!, [scope, ...deps]);
+}
+
+export function useScoped<T>(compute: () => T) {
+  const scope = useReactScope();
+  return React.useMemo(() => scoped(compute, scope)!, [scope]);
+}

package/src/hooks/use-slider-preview.ts

@@ -0,0 +1,126 @@
+import * as React from 'react';
+
+import { effect, signal } from 'maverick.js';
+import { EventsController, listenEvent } from 'maverick.js/std';
+import { updateSliderPreviewPlacement, type SliderOrientation } from 'vidstack';
+
+/**
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-slider-preview}
+ */
+export function useSliderPreview({
+  clamp = false,
+  offset = 0,
+  orientation = 'horizontal',
+}: UseSliderPreview = {}) {
+  const [rootRef, setRootRef] = React.useState<HTMLElement | null>(null),
+    [previewRef, setPreviewRef] = React.useState<HTMLElement | null>(null),
+    [pointerValue, setPointerValue] = React.useState(0),
+    [isVisible, setIsVisible] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!rootRef) return;
+
+    const dragging = signal(false);
+
+    function updatePointerValue(event: PointerEvent) {
+      if (!rootRef) return;
+      setPointerValue(getPointerValue(rootRef, event, orientation));
+    }
+
+    return effect(() => {
+      if (!dragging()) {
+        new EventsController(rootRef)
+          .add('pointerenter', () => {
+            setIsVisible(true);
+            previewRef?.setAttribute('data-visible', '');
+          })
+          .add('pointerdown', (event) => {
+            dragging.set(true);
+            updatePointerValue(event);
+          })
+          .add('pointerleave', () => {
+            setIsVisible(false);
+            previewRef?.removeAttribute('data-visible');
+          })
+          .add('pointermove', updatePointerValue);
+      }
+
+      previewRef?.setAttribute('data-dragging', '');
+
+      new EventsController(document)
+        .add('pointerup', (event) => {
+          dragging.set(false);
+          previewRef?.removeAttribute('data-dragging');
+          updatePointerValue(event);
+        })
+        .add('pointermove', updatePointerValue)
+        .add('touchmove', (e) => e.preventDefault(), { passive: false });
+    });
+  }, [rootRef]);
+
+  React.useEffect(() => {
+    if (previewRef) {
+      previewRef.style.setProperty('--slider-pointer', pointerValue + '%');
+    }
+  }, [previewRef, pointerValue]);
+
+  React.useEffect(() => {
+    if (!previewRef) return;
+
+    const update = () => {
+      updateSliderPreviewPlacement(previewRef, {
+        offset,
+        clamp,
+        orientation,
+      });
+    };
+
+    update();
+    const resize = new ResizeObserver(update);
+    resize.observe(previewRef);
+    return () => resize.disconnect();
+  }, [previewRef, clamp, offset, orientation]);
+
+  return {
+    previewRootRef: setRootRef,
+    previewRef: setPreviewRef,
+    previewValue: pointerValue,
+    isPreviewVisible: isVisible,
+  };
+}
+
+export interface UseSliderPreview {
+  /**
+   * Whether the preview should be clamped to the start and end of the slider root. If `true` the
+   * preview won't be placed outside the root bounds.
+   */
+  clamp?: boolean;
+  /**
+   * The distance in pixels between the preview and the slider root. You can also set
+   * the CSS variable `--media-slider-preview-offset` to adjust this offset.
+   */
+  offset?: number;
+  /**
+   * The orientation of the slider.
+   */
+  orientation?: SliderOrientation;
+}
+
+function getPointerValue(root: HTMLElement, event: PointerEvent, orientation: SliderOrientation) {
+  let thumbPositionRate: number,
+    rect = root.getBoundingClientRect();
+
+  if (orientation === 'vertical') {
+    const { bottom: trackBottom, height: trackHeight } = rect;
+    thumbPositionRate = (trackBottom - event.clientY) / trackHeight;
+  } else {
+    const { left: trackLeft, width: trackWidth } = rect;
+    thumbPositionRate = (event.clientX - trackLeft) / trackWidth;
+  }
+
+  return round(Math.max(0, Math.min(100, 100 * thumbPositionRate)));
+}
+
+function round(num: number) {
+  return Number(num.toFixed(3));
+}

package/src/hooks/use-slider-state.ts

@@ -0,0 +1,63 @@
+import * as React from 'react';
+
+import { useSignal, useSignalRecord, useStateContext } from 'maverick.js/react';
+import { sliderState, type SliderState } from 'vidstack';
+
+import {
+  SliderInstance,
+  type TimeSliderInstance,
+  type VolumeSliderInstance,
+} from '../components/primitives/instances';
+
+const sliderStateRecord = SliderInstance.state.record,
+  initialSliderStore = Object.keys(sliderStateRecord).reduce(
+    (store, prop) => ({
+      ...store,
+      [prop]() {
+        return sliderStateRecord[prop];
+      },
+    }),
+    {},
+  );
+
+/**
+ * This hook is used to subscribe to a specific slider state.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-slider-state}
+ */
+export function useSliderState<T extends keyof SliderState>(
+  prop: T,
+  ref?: React.RefObject<SliderInstance | VolumeSliderInstance | TimeSliderInstance | null>,
+): SliderState[T] {
+  const $state = useStateContext(sliderState);
+
+  if (__DEV__ && !$state && !ref) {
+    console.warn(
+      `[vidstack] \`useSliderState\` requires \`RefObject<SliderInstance>\` argument if called` +
+        ' outside of a slider component',
+    );
+  }
+
+  return useSignal((ref?.current?.$state || $state || initialSliderStore)[prop]);
+}
+
+/**
+ * This hook is used to subscribe to the current slider state on the given or nearest slider
+ * component.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/api/hooks/use-slider-state#store}
+ */
+export function useSliderStore(
+  ref?: React.RefObject<SliderInstance | VolumeSliderInstance | TimeSliderInstance | null>,
+): Readonly<SliderState> {
+  const $state = useStateContext(sliderState);
+
+  if (__DEV__ && !$state && !ref) {
+    console.warn(
+      `[vidstack] \`useSliderStore\` requires \`RefObject<SliderInstance>\` argument if called` +
+        ' outside of a slider component',
+    );
+  }
+
+  return useSignalRecord(ref?.current ? ref.current.$state : $state || initialSliderStore);
+}