@hanifhan1f/vidstack 1.12.13

package/src/components/ui/sliders/slider/events-controller.ts

@@ -0,0 +1,383 @@
+import throttle from 'just-throttle';
+import {
+  effect,
+  hasProvidedContext,
+  useContext,
+  ViewController,
+  type ReadSignal,
+} from 'maverick.js';
+import { EventsController, isNull, isNumber, listenEvent } from 'maverick.js/std';
+
+import type { MediaContext } from '../../../../core/api/media-context';
+import { isTouchPinchEvent } from '../../../../utils/dom';
+import type {
+  SliderDragEndEvent,
+  SliderDragStartEvent,
+  SliderDragValueChangeEvent,
+  SliderEvents,
+  SliderValueChangeEvent,
+} from './api/events';
+import type { SliderState } from './api/state';
+import {
+  sliderObserverContext,
+  type SliderObserverContext as SliderObserver,
+} from './slider-context';
+import type { SliderControllerProps } from './slider-controller';
+import { getValueFromRate } from './utils';
+
+/**
+ * The direction to move the thumb, associated with key symbols.
+ */
+const SliderKeyDirection = {
+  Left: -1,
+  ArrowLeft: -1,
+  Up: 1,
+  ArrowUp: 1,
+  Right: 1,
+  ArrowRight: 1,
+  Down: -1,
+  ArrowDown: -1,
+} as const;
+
+export interface SliderEventDelegate {
+  swipeGesture?: ReadSignal<boolean>;
+  isDisabled(): boolean;
+  getValue?(): number;
+  getStep(): number;
+  getKeyStep(): number;
+  roundValue(value: number): number;
+  onValueChange?(event: SliderValueChangeEvent): unknown;
+  onDragStart?(event: SliderDragStartEvent): unknown;
+  onDragEnd?(event: SliderDragEndEvent): unknown;
+  onDragValueChange?(event: SliderDragValueChangeEvent): unknown;
+}
+
+export class SliderEventsController extends ViewController<
+  SliderControllerProps,
+  SliderState,
+  SliderEvents
+> {
+  #delegate: SliderEventDelegate;
+  #media: MediaContext;
+  #observer?: SliderObserver;
+
+  constructor(delegate: SliderEventDelegate, media: MediaContext) {
+    super();
+    this.#delegate = delegate;
+    this.#media = media;
+  }
+
+  protected override onSetup(): void {
+    if (hasProvidedContext(sliderObserverContext)) {
+      this.#observer = useContext(sliderObserverContext);
+    }
+  }
+
+  protected override onConnect(el: HTMLElement) {
+    effect(this.#attachEventListeners.bind(this, el));
+    effect(this.#attachPointerListeners.bind(this, el));
+    if (this.#delegate.swipeGesture) effect(this.#watchSwipeGesture.bind(this));
+  }
+
+  #watchSwipeGesture() {
+    const { pointer } = this.#media.$state;
+
+    if (pointer() !== 'coarse' || !this.#delegate.swipeGesture!()) {
+      this.#provider = null;
+      return;
+    }
+
+    this.#provider = this.#media.player.el?.querySelector(
+      'media-provider,[data-media-provider]',
+    ) as HTMLElement | null;
+
+    if (!this.#provider) return;
+
+    new EventsController(this.#provider)
+      .add('touchstart', this.#onTouchStart.bind(this), {
+        passive: true,
+      })
+      .add('touchmove', this.#onTouchMove.bind(this), { passive: false });
+  }
+
+  #provider: HTMLElement | null = null;
+  #touch: Touch | null = null;
+  #touchStartValue: number | null = null;
+  #onTouchStart(event: TouchEvent) {
+    this.#touch = event.touches[0];
+  }
+
+  #onTouchMove(event: TouchEvent) {
+    if (isNull(this.#touch) || isTouchPinchEvent(event)) return;
+
+    const touch = event.touches[0],
+      xDiff = touch.clientX - this.#touch.clientX,
+      yDiff = touch.clientY - this.#touch.clientY,
+      isDragging = this.$state.dragging();
+
+    if (!isDragging && Math.abs(yDiff) > 5) {
+      return;
+    }
+
+    if (isDragging) return;
+
+    event.preventDefault();
+
+    if (Math.abs(xDiff) > 20) {
+      this.#touch = touch;
+      this.#touchStartValue = this.$state.value();
+      this.#onStartDragging(this.#touchStartValue, event);
+    }
+  }
+
+  #attachEventListeners(el: HTMLElement) {
+    const { hidden } = this.$props;
+
+    listenEvent(el, 'focus', this.#onFocus.bind(this));
+
+    if (hidden() || this.#delegate.isDisabled()) return;
+
+    new EventsController(el)
+      .add('keyup', this.#onKeyUp.bind(this))
+      .add('keydown', this.#onKeyDown.bind(this))
+      .add('pointerenter', this.#onPointerEnter.bind(this))
+      .add('pointermove', this.#onPointerMove.bind(this))
+      .add('pointerleave', this.#onPointerLeave.bind(this))
+      .add('pointerdown', this.#onPointerDown.bind(this));
+  }
+
+  #attachPointerListeners(el: HTMLElement) {
+    if (this.#delegate.isDisabled() || !this.$state.dragging()) return;
+
+    new EventsController(document)
+      .add('pointerup', this.#onDocumentPointerUp.bind(this), { capture: true })
+      .add('pointermove', this.#onDocumentPointerMove.bind(this))
+      .add('touchmove', this.#onDocumentTouchMove.bind(this), {
+        passive: false,
+      });
+  }
+
+  #onFocus() {
+    this.#updatePointerValue(this.$state.value());
+  }
+
+  #updateValue(newValue: number, trigger?: Event) {
+    const { value, min, max, dragging } = this.$state;
+
+    const clampedValue = Math.max(min(), Math.min(newValue, max()));
+    value.set(clampedValue);
+
+    const event = this.createEvent('value-change', { detail: clampedValue, trigger });
+    this.dispatch(event);
+    this.#delegate.onValueChange?.(event);
+
+    if (dragging()) {
+      const event = this.createEvent('drag-value-change', { detail: clampedValue, trigger });
+      this.dispatch(event);
+      this.#delegate.onDragValueChange?.(event);
+    }
+  }
+
+  #updatePointerValue(value: number, trigger?: Event) {
+    const { pointerValue, dragging } = this.$state;
+    pointerValue.set(value);
+    this.dispatch('pointer-value-change', { detail: value, trigger });
+    if (dragging()) {
+      this.#updateValue(value, trigger);
+    }
+  }
+
+  #getPointerValue(event: PointerEvent) {
+    let thumbPositionRate: number,
+      rect = this.el!.getBoundingClientRect(),
+      { min, max } = this.$state;
+
+    if (this.$props.orientation() === 'vertical') {
+      const { bottom: trackBottom, height: trackHeight } = rect;
+      thumbPositionRate = (trackBottom - event.clientY) / trackHeight;
+    } else {
+      if (this.#touch && isNumber(this.#touchStartValue)) {
+        const { width } = this.#provider!.getBoundingClientRect(),
+          rate = (event.clientX - this.#touch.clientX) / width,
+          range = max() - min(),
+          diff = range * Math.abs(rate);
+        thumbPositionRate =
+          (rate < 0 ? this.#touchStartValue - diff : this.#touchStartValue + diff) / range;
+      } else {
+        const { left: trackLeft, width: trackWidth } = rect;
+        thumbPositionRate = (event.clientX - trackLeft) / trackWidth;
+      }
+    }
+
+    return Math.max(
+      min(),
+      Math.min(
+        max(),
+        this.#delegate.roundValue(
+          getValueFromRate(min(), max(), thumbPositionRate, this.#delegate.getStep()),
+        ),
+      ),
+    );
+  }
+
+  #onPointerEnter(event: PointerEvent) {
+    this.$state.pointing.set(true);
+  }
+
+  #onPointerMove(event: PointerEvent) {
+    const { dragging } = this.$state;
+    // Avoid double updates - use document pointer move.
+    if (dragging()) return;
+    this.#updatePointerValue(this.#getPointerValue(event), event);
+  }
+
+  #onPointerLeave(event: PointerEvent) {
+    this.$state.pointing.set(false);
+  }
+
+  #onPointerDown(event: PointerEvent) {
+    if (event.button !== 0) return;
+    const value = this.#getPointerValue(event);
+    this.#onStartDragging(value, event);
+    this.#updatePointerValue(value, event);
+  }
+
+  #onStartDragging(value: number, trigger: Event) {
+    const { dragging } = this.$state;
+
+    if (dragging()) return;
+    dragging.set(true);
+
+    this.#media.remote.pauseControls(trigger);
+
+    const event = this.createEvent('drag-start', { detail: value, trigger });
+    this.dispatch(event);
+    this.#delegate.onDragStart?.(event);
+    this.#observer?.onDragStart?.();
+  }
+
+  #onStopDragging(value: number, trigger: Event) {
+    const { dragging } = this.$state;
+
+    if (!dragging()) return;
+    dragging.set(false);
+
+    this.#media.remote.resumeControls(trigger);
+
+    const event = this.createEvent('drag-end', { detail: value, trigger });
+    this.dispatch(event);
+    this.#delegate.onDragEnd?.(event);
+    this.#touch = null;
+    this.#touchStartValue = null;
+    this.#observer?.onDragEnd?.();
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // Keyboard Events
+  // -------------------------------------------------------------------------------------------
+
+  #lastDownKey!: string;
+  #repeatedKeys = false;
+
+  #onKeyDown(event: KeyboardEvent) {
+    const isValidKey = Object.keys(SliderKeyDirection).includes(event.key);
+
+    if (!isValidKey) return;
+
+    const { key } = event,
+      jumpValue = this.#calcJumpValue(event);
+
+    if (!isNull(jumpValue)) {
+      this.#updatePointerValue(jumpValue, event);
+      this.#updateValue(jumpValue, event);
+      return;
+    }
+
+    const newValue = this.#calcNewKeyValue(event);
+
+    if (!this.#repeatedKeys) {
+      this.#repeatedKeys = key === this.#lastDownKey;
+      if (!this.$state.dragging() && this.#repeatedKeys) {
+        this.#onStartDragging(newValue, event);
+      }
+    }
+
+    this.#updatePointerValue(newValue, event);
+
+    this.#lastDownKey = key;
+  }
+
+  #onKeyUp(event: KeyboardEvent) {
+    const isValidKey = Object.keys(SliderKeyDirection).includes(event.key);
+    if (!isValidKey || !isNull(this.#calcJumpValue(event))) return;
+
+    const newValue = this.#repeatedKeys ? this.$state.pointerValue() : this.#calcNewKeyValue(event);
+    this.#updateValue(newValue, event);
+    this.#onStopDragging(newValue, event);
+
+    this.#lastDownKey = '';
+    this.#repeatedKeys = false;
+  }
+
+  #calcJumpValue(event: KeyboardEvent) {
+    let key = event.key,
+      { min, max } = this.$state;
+
+    if (key === 'Home' || key === 'PageUp') {
+      return min();
+    } else if (key === 'End' || key === 'PageDown') {
+      return max();
+    } else if (!event.metaKey && /^[0-9]$/.test(key)) {
+      return ((max() - min()) / 10) * Number(key);
+    }
+
+    return null;
+  }
+
+  #calcNewKeyValue(event: KeyboardEvent) {
+    const { key, shiftKey } = event;
+
+    event.preventDefault();
+    event.stopPropagation();
+
+    const { shiftKeyMultiplier } = this.$props;
+    const { min, max, value, pointerValue } = this.$state,
+      step = this.#delegate.getStep(),
+      keyStep = this.#delegate.getKeyStep();
+
+    const modifiedStep = !shiftKey ? keyStep : keyStep * shiftKeyMultiplier(),
+      direction = Number(SliderKeyDirection[key]),
+      diff = modifiedStep * direction,
+      currentValue = this.#repeatedKeys ? pointerValue() : (this.#delegate.getValue?.() ?? value()),
+      steps = (currentValue + diff) / step;
+
+    return Math.max(min(), Math.min(max(), Number((step * steps).toFixed(3))));
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // Document (Pointer Events)
+  // -------------------------------------------------------------------------------------------
+
+  #onDocumentPointerUp(event: PointerEvent) {
+    if (event.button !== 0) return;
+
+    event.preventDefault();
+    event.stopImmediatePropagation();
+
+    const value = this.#getPointerValue(event);
+    this.#updatePointerValue(value, event);
+    this.#onStopDragging(value, event);
+  }
+
+  #onDocumentTouchMove(event: TouchEvent) {
+    event.preventDefault();
+  }
+
+  #onDocumentPointerMove = throttle(
+    (event: PointerEvent) => {
+      this.#updatePointerValue(this.#getPointerValue(event), event);
+    },
+    20,
+    { leading: true },
+  );
+}

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

@@ -0,0 +1,12 @@
+import { createContext } from 'maverick.js';
+
+import type { FormatTimeOptions } from '../../../../utils/time';
+
+export const sliderValueFormatContext = createContext<SliderValueFormat>(() => ({}));
+
+export interface SliderValueFormat {
+  default?: 'value' | 'percent' | 'time';
+  value?(value: number): string | number;
+  percent?(percent: number, decimalPlaces: number): string | number;
+  time?(value: number, options?: FormatTimeOptions): string;
+}

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

@@ -0,0 +1,18 @@
+import { createContext, type ReadSignal, type WriteSignal } from 'maverick.js';
+
+import type { SliderOrientation } from './types';
+
+export interface SliderContext {
+  disabled: ReadSignal<boolean>;
+  orientation: ReadSignal<SliderOrientation>;
+  preview: WriteSignal<HTMLElement | null>;
+}
+
+export const sliderContext = createContext<SliderContext>();
+
+export interface SliderObserverContext {
+  onDragStart?(): void;
+  onDragEnd?(): void;
+}
+
+export const sliderObserverContext = createContext<SliderObserverContext>();

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

@@ -0,0 +1,211 @@
+import {
+  effect,
+  hasProvidedContext,
+  onDispose,
+  peek,
+  provideContext,
+  signal,
+  ViewController,
+} from 'maverick.js';
+import { animationFrameThrottle, ariaBool } from 'maverick.js/std';
+
+import { useMediaContext, type MediaContext } from '../../../../core/api/media-context';
+import { FocusVisibleController } from '../../../../foundation/observers/focus-visible';
+import { IntersectionObserverController } from '../../../../foundation/observers/intersection-observer';
+import { observeVisibility, setAttributeIfEmpty } from '../../../../utils/dom';
+import { round } from '../../../../utils/number';
+import type { SliderEvents } from './api/events';
+import type { SliderState } from './api/state';
+import { SliderEventsController, type SliderEventDelegate } from './events-controller';
+import { sliderValueFormatContext } from './format';
+import { sliderContext } from './slider-context';
+import type { SliderOrientation } from './types';
+import { getClampedValue } from './utils';
+
+export interface SliderDelegate extends Omit<SliderEventDelegate, '_getOrientation'> {
+  aria: {
+    valueNow(): number;
+    valueText(): string;
+    valueMin?(): number;
+    valueMax?(): number;
+  };
+}
+
+export class SliderController extends ViewController<
+  SliderControllerProps,
+  SliderState,
+  SliderEvents
+> {
+  static props: SliderControllerProps = {
+    hidden: false,
+    disabled: false,
+    step: 1,
+    keyStep: 1,
+    orientation: 'horizontal',
+    shiftKeyMultiplier: 5,
+  };
+
+  #media!: MediaContext;
+  #delegate: SliderDelegate;
+  #isVisible = signal(true);
+  #isIntersecting = signal(true);
+
+  constructor(delegate: SliderDelegate) {
+    super();
+    this.#delegate = delegate;
+  }
+
+  protected override onSetup(): void {
+    this.#media = useMediaContext();
+
+    const focus = new FocusVisibleController();
+    focus.attach(this);
+
+    // @ts-expect-error - overwrite readonly
+    this.$state.focused = focus.focused.bind(focus);
+
+    if (!hasProvidedContext(sliderValueFormatContext)) {
+      provideContext(sliderValueFormatContext, {
+        default: 'value',
+      });
+    }
+
+    provideContext(sliderContext, {
+      orientation: this.$props.orientation,
+      disabled: this.#delegate.isDisabled,
+      preview: signal<HTMLElement | null>(null),
+    });
+
+    effect(this.#watchValue.bind(this));
+    effect(this.#watchStep.bind(this));
+    effect(this.#watchDisabled.bind(this));
+
+    this.#setupAttrs();
+
+    new SliderEventsController(this.#delegate, this.#media).attach(this);
+    new IntersectionObserverController({
+      callback: this.#onIntersectionChange.bind(this),
+    }).attach(this);
+  }
+
+  protected override onAttach(el: HTMLElement) {
+    setAttributeIfEmpty(el, 'role', 'slider');
+    setAttributeIfEmpty(el, 'tabindex', '0');
+    setAttributeIfEmpty(el, 'autocomplete', 'off');
+    if (__SERVER__) this.#watchCSSVars();
+    else effect(this.#watchCSSVars.bind(this));
+  }
+
+  protected override onConnect(el: HTMLElement): void {
+    onDispose(observeVisibility(el, this.#isVisible.set));
+    effect(this.#watchHidden.bind(this));
+  }
+
+  #onIntersectionChange(entries: IntersectionObserverEntry[]) {
+    this.#isIntersecting.set(entries[0].isIntersecting);
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // Watch
+  // -------------------------------------------------------------------------------------------
+
+  #watchHidden() {
+    const { hidden } = this.$props;
+    this.$state.hidden.set(hidden() || !this.#isVisible() || !this.#isIntersecting.bind(this));
+  }
+
+  #watchValue() {
+    const { dragging, value, min, max } = this.$state;
+    if (peek(dragging)) return;
+    value.set(getClampedValue(min(), max(), value(), this.#delegate.getStep()));
+  }
+
+  #watchStep() {
+    this.$state.step.set(this.#delegate.getStep());
+  }
+
+  #watchDisabled() {
+    if (!this.#delegate.isDisabled()) return;
+    const { dragging, pointing } = this.$state;
+    dragging.set(false);
+    pointing.set(false);
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // ARIA
+  // -------------------------------------------------------------------------------------------
+
+  #getARIADisabled() {
+    return ariaBool(this.#delegate.isDisabled());
+  }
+
+  // -------------------------------------------------------------------------------------------
+  // Attributes
+  // -------------------------------------------------------------------------------------------
+
+  #setupAttrs() {
+    const { orientation } = this.$props,
+      { dragging, active, pointing } = this.$state;
+
+    this.setAttributes({
+      'data-dragging': dragging,
+      'data-pointing': pointing,
+      'data-active': active,
+      'aria-disabled': this.#getARIADisabled.bind(this),
+      'aria-valuemin': this.#delegate.aria.valueMin ?? this.$state.min,
+      'aria-valuemax': this.#delegate.aria.valueMax ?? this.$state.max,
+      'aria-valuenow': this.#delegate.aria.valueNow,
+      'aria-valuetext': this.#delegate.aria.valueText,
+      'aria-orientation': orientation,
+    });
+  }
+
+  #watchCSSVars() {
+    const { fillPercent, pointerPercent } = this.$state;
+    this.#updateSliderVars(round(fillPercent(), 3), round(pointerPercent(), 3));
+  }
+
+  #updateSliderVars = animationFrameThrottle((fillPercent: number, pointerPercent: number) => {
+    this.el?.style.setProperty('--slider-fill', fillPercent + '%');
+    this.el?.style.setProperty('--slider-pointer', pointerPercent + '%');
+  });
+}
+
+export interface SliderControllerProps {
+  /**
+   * Whether the slider should be disabled (non-interactive).
+   */
+  disabled: boolean;
+  /**
+   * Provides a hint that the slider is not visible and stops all events and expensive updates to
+   * be more power efficient.
+   */
+  hidden: boolean;
+  /**
+   * The orientation of the slider.
+   */
+  orientation: SliderOrientation;
+  /**
+   * A number that specifies the granularity that the slider value must adhere to.
+   *
+   * A step is an abstract unit that may carry a different type of measure depending on the type of
+   * slider. For example, for the volume slider each step is 1% of volume, and for the time slider
+   * it is 1 second which is a varying percentage depending on the media duration.
+   */
+  step: number;
+  /**
+   * ♿ **ARIA:** A number that specifies the number of steps taken when interacting with
+   * the slider via keyboard.
+   *
+   * A step is an abstract unit that may carry different type of measure depending on the type of
+   * slider. For example, for the volume slider each step is 1% of volume, and for the time slider
+   * it is 1 second which is a varying percentage depending on the media duration.
+   */
+  keyStep: number;
+  /**
+   * ♿ **ARIA:** A number that will be used to multiply the `keyStep` when the `Shift` key
+   * is held down and the slider value is changed by pressing `LeftArrow` or `RightArrow`. Think
+   * of it as `keyStep * shiftKeyMultiplier`.
+   */
+  shiftKeyMultiplier: number;
+}