@hanifhan1f/vidstack 1.12.13

package/src/components/ui/sliders/slider/slider.ts

@@ -0,0 +1,94 @@
+import { Component, effect } from 'maverick.js';
+
+import { round } from '../../../../utils/number';
+import type { SliderCSSVars } from './api/cssvars';
+import type { SliderEvents } from './api/events';
+import { sliderState, type SliderState } from './api/state';
+import { SliderController, type SliderControllerProps } from './slider-controller';
+
+/**
+ * Versatile and user-friendly input control designed for seamless cross-browser compatibility and
+ * accessibility with ARIA support. It offers a smooth user experience for both mouse and touch
+ * interactions and is highly customizable in terms of styling. Users can effortlessly input numeric
+ * values within a specified range, defined by a minimum and maximum value.
+ *
+ * @attr data-dragging - Whether slider thumb is being dragged.
+ * @attr data-pointing - Whether user's pointing device is over slider.
+ * @attr data-active - Whether slider is being interacted with.
+ * @attr data-focus - Whether slider is being keyboard focused.
+ * @attr data-hocus - Whether slider is being keyboard focused or hovered over.
+ * @docs {@link https://www.vidstack.io/docs/player/components/sliders/slider}
+ */
+export class Slider extends Component<SliderProps, SliderState, SliderEvents, SliderCSSVars> {
+  static props: SliderProps = {
+    ...SliderController.props,
+    min: 0,
+    max: 100,
+    value: 0,
+  };
+
+  static state = sliderState;
+
+  constructor() {
+    super();
+    new SliderController({
+      getStep: this.$props.step,
+      getKeyStep: this.$props.keyStep,
+      roundValue: Math.round,
+      isDisabled: this.$props.disabled,
+      aria: {
+        valueNow: this.#getARIAValueNow.bind(this),
+        valueText: this.#getARIAValueText.bind(this),
+      },
+    });
+  }
+
+  protected override onSetup() {
+    effect(this.#watchValue.bind(this));
+    effect(this.#watchMinMax.bind(this));
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // Props
+  // -------------------------------------------------------------------------------------------
+
+  #getARIAValueNow() {
+    const { value } = this.$state;
+    return Math.round(value());
+  }
+
+  #getARIAValueText() {
+    const { value, max } = this.$state;
+    return round((value() / max()) * 100, 2) + '%';
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // Watch
+  // -------------------------------------------------------------------------------------------
+
+  #watchValue() {
+    const { value } = this.$props;
+    this.$state.value.set(value());
+  }
+
+  #watchMinMax() {
+    const { min, max } = this.$props;
+    this.$state.min.set(min());
+    this.$state.max.set(max());
+  }
+}
+
+export interface SliderProps extends SliderControllerProps {
+  /**
+   * The lowest slider value in the range of permitted values.
+   */
+  min: number;
+  /**
+   * The greatest slider value in the range of permitted values.
+   */
+  max: number;
+  /**
+   * The current slider value.
+   */
+  value: number;
+}

package/src/components/ui/sliders/slider/types.ts

@@ -0,0 +1 @@
+export type SliderOrientation = 'horizontal' | 'vertical';

package/src/components/ui/sliders/slider/utils.ts

@@ -0,0 +1,14 @@
+import { clampNumber, getNumberOfDecimalPlaces, round } from '../../../../utils/number';
+
+export function getClampedValue(min: number, max: number, value: number, step: number) {
+  return clampNumber(min, round(value, getNumberOfDecimalPlaces(step)), max);
+}
+
+export function getValueFromRate(min: number, max: number, rate: number, step: number) {
+  const boundRate = clampNumber(0, rate, 1),
+    range = max - min,
+    fill = range * boundRate,
+    stepRatio = fill / step,
+    steps = step * Math.round(stepRatio);
+  return min + steps;
+}

package/src/components/ui/sliders/slider-preview.ts

@@ -0,0 +1,131 @@
+import { Component, effect, onDispose, useContext, useState } from 'maverick.js';
+import { animationFrameThrottle } from 'maverick.js/std';
+
+import { Slider } from './slider/slider';
+import { sliderContext, type SliderContext } from './slider/slider-context';
+import type { SliderOrientation } from './slider/types';
+
+/**
+ * Used to provide users with a real-time or interactive preview of the value or selection they
+ * are making as they move the slider thumb. This can include displaying the current pointer
+ * value numerically, or displaying a thumbnail over the time slider.
+ *
+ * @attr data-visible - Whether the preview is visible.
+ * @docs {@link https://www.vidstack.io/docs/player/components/sliders/slider#preview}
+ */
+export class SliderPreview extends Component<SliderPreviewProps> {
+  static props: SliderPreviewProps = {
+    offset: 0,
+    noClamp: false,
+  };
+
+  #slider!: SliderContext;
+
+  protected override onSetup(): void {
+    this.#slider = useContext(sliderContext);
+
+    const { active } = useState(Slider.state);
+    this.setAttributes({
+      'data-visible': active,
+    });
+  }
+
+  protected override onAttach(el: HTMLElement): void {
+    Object.assign(el.style, {
+      position: 'absolute',
+      top: 0,
+      left: 0,
+      width: 'max-content',
+    });
+  }
+
+  protected override onConnect(el: HTMLElement): void {
+    const { preview } = this.#slider;
+    preview.set(el);
+    onDispose(() => preview.set(null));
+
+    effect(this.#updatePlacement.bind(this));
+
+    const resize = new ResizeObserver(this.#updatePlacement.bind(this));
+    resize.observe(el);
+    onDispose(() => resize.disconnect());
+  }
+
+  #updatePlacement = animationFrameThrottle(() => {
+    const { disabled, orientation } = this.#slider;
+
+    if (disabled()) return;
+
+    const el = this.el,
+      { offset, noClamp } = this.$props;
+
+    if (!el) return;
+
+    updateSliderPreviewPlacement(el, {
+      clamp: !noClamp(),
+      offset: offset(),
+      orientation: orientation(),
+    });
+  });
+}
+
+export function updateSliderPreviewPlacement(
+  el: HTMLElement,
+  {
+    clamp,
+    offset,
+    orientation,
+  }: {
+    clamp: boolean;
+    offset: number;
+    orientation: SliderOrientation;
+  },
+) {
+  const computedStyle = getComputedStyle(el),
+    width = parseFloat(computedStyle.width),
+    height = parseFloat(computedStyle.height),
+    styles: Record<string, string | null> = {
+      top: null,
+      right: null,
+      bottom: null,
+      left: null,
+    };
+
+  styles[orientation === 'horizontal' ? 'bottom' : 'left'] =
+    `calc(100% + var(--media-slider-preview-offset, ${offset}px))`;
+
+  if (orientation === 'horizontal') {
+    const widthHalf = width / 2;
+    if (!clamp) {
+      styles.left = `calc(var(--slider-pointer) - ${widthHalf}px)`;
+    } else {
+      const leftClamp = `max(0px, calc(var(--slider-pointer) - ${widthHalf}px))`,
+        rightClamp = `calc(100% - ${width}px)`;
+      styles.left = `min(${leftClamp}, ${rightClamp})`;
+    }
+  } else {
+    const heightHalf = height / 2;
+    if (!clamp) {
+      styles.bottom = `calc(var(--slider-pointer) - ${heightHalf}px)`;
+    } else {
+      const topClamp = `max(${heightHalf}px, calc(var(--slider-pointer) - ${heightHalf}px))`,
+        bottomClamp = `calc(100% - ${height}px)`;
+      styles.bottom = `min(${topClamp}, ${bottomClamp})`;
+    }
+  }
+
+  Object.assign(el.style, styles);
+}
+
+export interface SliderPreviewProps {
+  /**
+   * The distance in pixels between the preview and the slider. You can also set
+   * the CSS variable `--media-slider-preview-offset` to adjust this offset.
+   */
+  offset: number;
+  /**
+   * By default, the preview will be clamped to the left and right of the slider track. If this
+   * is set to `true`, the preview will flow outside of the container when at the edges.
+   */
+  noClamp: boolean;
+}

package/src/components/ui/sliders/slider-thumbnail.ts

@@ -0,0 +1,28 @@
+import { useState, type StateContext } from 'maverick.js';
+
+import { Thumbnail } from '../thumbnails/thumbnail';
+import { sliderState } from './slider/api/state';
+import { Slider } from './slider/slider';
+
+/**
+ * Used to display preview thumbnails when the user is hovering or dragging the time slider.
+ * The time ranges in the WebVTT file will automatically be matched based on the current slider
+ * pointer position.
+ *
+ * @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/sliders/slider-thumbnail}
+ */
+export class SliderThumbnail extends Thumbnail {
+  #slider!: StateContext<typeof sliderState>;
+
+  protected override onAttach(el: HTMLElement) {
+    this.#slider = useState(Slider.state);
+  }
+
+  protected override getTime() {
+    const { duration, clipStartTime } = this.media.$state;
+    return clipStartTime() + this.#slider.pointerRate() * duration();
+  }
+}

package/src/components/ui/sliders/slider-value.ts

@@ -0,0 +1,122 @@
+import {
+  Component,
+  computed,
+  method,
+  useContext,
+  useState,
+  type ReadSignal,
+  type StateContext,
+} from 'maverick.js';
+
+import { round } from '../../../utils/number';
+import { formatTime } from '../../../utils/time';
+import { Slider } from '../sliders/slider/slider';
+import type { SliderValueFormat } from './slider/format';
+import { sliderValueFormatContext } from './slider/format';
+
+/**
+ * Displays the specific numeric representation of the current or pointer value of the slider.
+ * When a user interacts with a slider by moving its thumb along the track, the slider value
+ * changes accordingly.
+ *
+ * @docs {@link https://www.vidstack.io/docs/player/components/sliders/slider-value}
+ */
+export class SliderValue extends Component<SliderValueProps> {
+  static props: SliderValueProps = {
+    type: 'pointer',
+    format: null,
+    showHours: false,
+    showMs: false,
+    padHours: null,
+    padMinutes: null,
+    decimalPlaces: 2,
+  };
+
+  #format!: SliderValueFormat;
+  #text!: ReadSignal<string>;
+  #slider!: StateContext<typeof Slider.state>;
+
+  protected override onSetup(): void {
+    this.#slider = useState(Slider.state);
+    this.#format = useContext(sliderValueFormatContext);
+    this.#text = computed(this.getValueText.bind(this));
+  }
+
+  /**
+   * Returns the current value formatted as text based on prop settings.
+   */
+  @method
+  getValueText() {
+    const {
+        type,
+        format: $format,
+        decimalPlaces,
+        padHours,
+        padMinutes,
+        showHours,
+        showMs,
+      } = this.$props,
+      { value: sliderValue, pointerValue, min, max } = this.#slider,
+      format = $format?.() ?? this.#format.default;
+
+    const value = type() === 'current' ? sliderValue() : pointerValue();
+
+    if (format === 'percent') {
+      const range = max() - min();
+      const percent = (value / range) * 100;
+      return (this.#format.percent ?? round)(percent, decimalPlaces()) + '%';
+    } else if (format === 'time') {
+      return (this.#format.time ?? formatTime)(value, {
+        padHrs: padHours(),
+        padMins: padMinutes(),
+        showHrs: showHours(),
+        showMs: showMs(),
+      });
+    } else {
+      return (this.#format.value?.(value) ?? value.toFixed(2)) + '';
+    }
+  }
+}
+
+export interface SliderValueProps {
+  /**
+   * Whether to use the slider's current value, or pointer value.
+   */
+  type: 'current' | 'pointer';
+  /**
+   * Determines how the value is formatted. By default it will use the most appropriate formatting,
+   * for the time slider that's time, and for volume percent.
+   */
+  format: 'value' | 'percent' | 'time' | null;
+  /**
+   * Whether the time should always show the hours unit, even if the time is less than
+   * 1 hour. Only available if the `format` prop is set to `time`.
+   *
+   * @example `20:30 -> 0:20:35`
+   */
+  showHours: boolean;
+  /**
+   * Whether the time should display milliseconds. Only available if the `format` prop is set to
+   * `time`.
+   */
+  showMs: boolean;
+  /**
+   * Whether the hours unit should be padded with zeroes to a length of 2. Only available if
+   * the `format` prop is set to `time`.
+   *
+   * @example `1:20:03 -> 01:20:03`
+   */
+  padHours: boolean | null;
+  /**
+   * Whether the minutes unit should be padded with zeroes to a length of 2. Setting this to `null`
+   * will pad minutes when hours is >=1. Only available if the `format` prop is set to `time`.
+   *
+   * @example `5:22 -> 05:22`
+   */
+  padMinutes: boolean | null;
+  /**
+   * Round the value when formatted as a percentage to the given number of decimal places. Only
+   * available if `format` prop is `percent`.
+   */
+  decimalPlaces: number;
+}

package/src/components/ui/sliders/slider-video.ts

@@ -0,0 +1,198 @@
+import { Component, effect, prop, State, useState, type StateContext } from 'maverick.js';
+import { EventsController, isNull, listenEvent, type DOMEvent } 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 { Slider } from './slider/slider';
+
+/**
+ * Used to load a low-resolution video to be displayed when the user is hovering over or dragging
+ * the time slider. The preview video will automatically be updated to be in-sync with the current
+ * preview position, so ensure it has the same length as the original media (i.e., same duration).
+ *
+ * @attr data-loading - Whether the video is loading.
+ * @attr data-error - Whether an error occurred loading video.
+ * @attr data-hidden - Whether the video is not ready or has failed to load.
+ * @docs {@link https://www.vidstack.io/docs/player/components/sliders/slider-video}
+ */
+export class SliderVideo extends Component<SliderVideoProps, SliderVideoState, SliderVideoEvents> {
+  static props: SliderVideoProps = {
+    src: null,
+    crossOrigin: null,
+  };
+
+  static state = new State<SliderVideoState>({
+    video: null,
+    src: null,
+    crossOrigin: null,
+    canPlay: false,
+    error: null,
+    hidden: false,
+  });
+
+  #media!: MediaContext;
+  #slider!: StateContext<typeof Slider.state>;
+
+  @prop
+  get video() {
+    return this.$state.video();
+  }
+
+  protected override onSetup(): void {
+    this.#media = useMediaContext();
+    this.#slider = useState(Slider.state);
+
+    this.#watchCrossOrigin();
+
+    this.setAttributes({
+      'data-loading': this.#isLoading.bind(this),
+      'data-hidden': this.$state.hidden,
+      'data-error': this.#hasError.bind(this),
+      'aria-hidden': $ariaBool(this.$state.hidden),
+    });
+  }
+
+  protected override onAttach(el: HTMLElement) {
+    effect(this.#watchVideo.bind(this));
+    effect(this.#watchSrc.bind(this));
+    effect(this.#watchCrossOrigin.bind(this));
+    effect(this.#watchHidden.bind(this));
+
+    effect(this.#onSrcChange.bind(this));
+    effect(this.#onUpdateTime.bind(this));
+  }
+
+  #watchVideo() {
+    const video = this.$state.video();
+
+    if (!video) return;
+
+    if (video.readyState >= 2) this.#onCanPlay();
+
+    new EventsController(video)
+      .add('canplay', this.#onCanPlay.bind(this))
+      .add('error', this.#onError.bind(this));
+  }
+
+  #watchSrc() {
+    const { src } = this.$state,
+      { canLoad } = this.#media.$state;
+    src.set(canLoad() ? this.$props.src() : null);
+  }
+
+  #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);
+  }
+
+  #isLoading() {
+    const { canPlay, hidden } = this.$state;
+    return !canPlay() && !hidden();
+  }
+
+  #hasError() {
+    const { error } = this.$state;
+    return !isNull(error);
+  }
+
+  #watchHidden() {
+    const { src, hidden } = this.$state,
+      { canLoad, duration } = this.#media.$state;
+    hidden.set(canLoad() && (!src() || this.#hasError() || !Number.isFinite(duration())));
+  }
+
+  #onSrcChange() {
+    const { src, canPlay, error } = this.$state;
+    src();
+    canPlay.set(false);
+    error.set(null);
+  }
+
+  #onCanPlay(event?: Event) {
+    const { canPlay, error } = this.$state;
+    canPlay.set(true);
+    error.set(null);
+    this.dispatch('can-play', { trigger: event });
+  }
+
+  #onError(event: ErrorEvent) {
+    const { canPlay, error } = this.$state;
+    canPlay.set(false);
+    error.set(event);
+    this.dispatch('error', { trigger: event });
+  }
+
+  #onUpdateTime() {
+    const { video, canPlay } = this.$state,
+      { duration } = this.#media.$state,
+      { pointerRate } = this.#slider,
+      media = video(),
+      canUpdate =
+        canPlay() && media && Number.isFinite(duration()) && Number.isFinite(pointerRate());
+
+    if (canUpdate) {
+      media!.currentTime = pointerRate() * duration();
+    }
+  }
+}
+
+export interface SliderVideoProps {
+  /**
+   * The URL of a media resource to use.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/src}
+   */
+  src: string | null;
+  /**
+   * 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 SliderVideoState {
+  video: HTMLVideoElement | null;
+  src: string | null;
+  crossOrigin: MediaCrossOrigin | null;
+  canPlay: boolean;
+  error: ErrorEvent | null;
+  hidden: boolean;
+}
+
+export interface SliderVideoEvents {
+  'can-play': SliderVideoCanPlayEvent;
+  error: SliderVideoErrorEvent;
+}
+
+/**
+ * Fired when the user agent can play the media, but estimates that **not enough** data has been
+ * loaded to play the media up to its end without having to stop for further buffering of content.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/canplay_event}
+ */
+export interface SliderVideoCanPlayEvent extends DOMEvent<void> {
+  target: SliderVideo;
+  /** The `canplay` media event. */
+  readonly trigger: Event;
+}
+
+/**
+ * Fired when media loading or playback has encountered any issues (for example, a network
+ * connectivity problem). The event detail contains a potential message containing more
+ * information about the error (empty string if nothing available), and a code that identifies
+ * the general type of error that occurred.
+ *
+ * @see {@link https://html.spec.whatwg.org/multipage/media.html#error-codes}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/error_event}
+ */
+export interface SliderVideoErrorEvent extends DOMEvent<void> {
+  target: SliderVideo;
+  /** The `error` media event. */
+  readonly trigger: Event;
+}