Scrubbing

/**
 * Scrubbing: changing a value by dragging sideways across something that names
 * it — a field's label, a handle inside the field — as an inspector's numbers
 * are dragged.
 *
 * - A press becomes a scrub only once it has travelled: a click is still a click.
 * - Travel is counted in whole steps, toward the end of the line in the writing
 *   direction; what is left over waits for the next movement. Shift makes a step
 *   large and Alt small, as they do for the arrow keys.
 * - The drag goes on outside what was pressed. A mouse is locked in place where
 *   the browser allows, so that the edge of the screen does not end it.
 * - Escape, a cancelled touch and the window losing focus take the scrub back.
 * - The page still scrolls: only a sideways drag belongs to the scrub.
 *
 * It reports steps, not values. What a step is, and where the range ends, is the
 * value's own business — which is also why a pointer held past an end has
 * nothing to unwind: the first step back is a step back.
 */
import { useCallback, useLayoutEffect, useRef } from "react";
import { isApplePlatform } from "../lib/platform.ts";

/** How far a press travels, in CSS pixels, before it is a scrub rather than a click. */
export const SCRUB_THRESHOLD = 3;

/** The travel, in CSS pixels, that makes one step. */
export const SCRUB_DISTANCE = 2;

export type ScrubSize = "small" | "normal" | "large";

export interface ScrubOptions {
  /** The travel that makes one step, when not `SCRUB_DISTANCE`. */
  readonly distance?: number | undefined;
  /** A press has travelled far enough to be a scrub. */
  readonly onScrubStart?: (() => void) | undefined;
  /** Whole steps since the last report: positive toward the end of the line, negative toward its start. */
  readonly onScrub: (steps: number, size: ScrubSize) => void;
  /** The pointer was released. */
  readonly onScrubEnd?: (() => void) | undefined;
  /** The scrub was taken back: by Escape, a cancelled touch, or the window losing focus. */
  readonly onScrubCancel?: (() => void) | undefined;
}

/** The size of step the modifiers ask for, as the arrow keys read them. */
export function scrubSize(modifiers: { readonly shiftKey: boolean; readonly altKey: boolean }): ScrubSize {
  return modifiers.shiftKey ? "large" : modifiers.altKey ? "small" : "normal";
}

/**
 * The whole steps a movement makes, and the travel left over toward the next:
 * `rest` is what the last movement left.
 */
export function scrubTravel(
  rest: number,
  pixels: number,
  distance: number = SCRUB_DISTANCE,
): { readonly steps: number; readonly rest: number } {
  const total = rest + pixels;
  const steps = Math.trunc(total / distance);
  // Not -0, which is no step either.
  return { steps: steps === 0 ? 0 : steps, rest: total - steps * distance };
}

/** What a press inside the scrubbed element may land on and keep for itself. */
const CONTROLS = "input, textarea, select, button, a[href], [contenteditable]";

interface Press {
  readonly pointer: number;
  /** Where the pointer was last seen. */
  x: number;
  rest: number;
  active: boolean;
  locked: boolean;
  sign: 1 | -1;
}

/**
 * Make `element` scrub. `options` is read at each event, so it may change.
 * Returns what undoes it.
 */
export function scrub(element: HTMLElement, options: () => ScrubOptions): () => void {
  const { style } = element;
  const before = {
    cursor: style.cursor,
    touchAction: style.touchAction,
    userSelect: style.userSelect,
    webkitUserSelect: style.getPropertyValue("-webkit-user-select"),
  };
  style.cursor = "ew-resize";
  // A drag up or down is still the page's; only a sideways one is the scrub's.
  style.touchAction = "pan-y";
  style.userSelect = "none";
  style.setProperty("-webkit-user-select", "none");
  element.dataset.scrub = "";

  let press: Press | null = null;
  // Whether the press now ending was a scrub: its click is not a click.
  let scrubbed = false;

  function finish(how: "end" | "cancel"): void {
    const current = press;
    if (current === null) return;
    press = null;
    window.removeEventListener("pointermove", onPointerMove, true);
    window.removeEventListener("pointerup", onPointerUp, true);
    window.removeEventListener("pointercancel", onPointerCancel, true);
    window.removeEventListener("blur", onBlur);
    document.removeEventListener("keydown", onKeyDown, true);
    document.removeEventListener("pointerlockchange", onLockChange);
    try {
      element.releasePointerCapture(current.pointer);
    } catch {
      // Not captured: the pointer is gone, or was never this element's.
    }
    if (document.pointerLockElement === element) document.exitPointerLock();
    delete element.dataset.scrubbing;
    if (!current.active) return;
    if (how === "end") options().onScrubEnd?.();
    else options().onScrubCancel?.();
  }

  /** Whether a press is one that may become a scrub. */
  function mine(event: MouseEvent): boolean {
    if (event.button !== 0) return false;
    // On a Mac, Control with a press asks for the context menu.
    if (event.ctrlKey && isApplePlatform()) return false;
    const target = event.target as Element | null;
    const control = target?.closest?.(CONTROLS) ?? null;
    // A control inside what scrubs — a field inside its own label — keeps its presses.
    return control === null || control === element || !element.contains(control);
  }

  function onMouseDown(event: MouseEvent): void {
    // No selection starts here to be dragged into the field beside it, which
    // WebKit would then give focus. The click is untouched: a label still works.
    if (mine(event)) event.preventDefault();
  }

  function onPointerDown(event: PointerEvent): void {
    if (press !== null || !event.isPrimary || !mine(event)) return;
    scrubbed = false;
    press = { pointer: event.pointerId, x: event.clientX, rest: 0, active: false, locked: false, sign: 1 };
    try {
      element.setPointerCapture(event.pointerId);
    } catch {
      // A pointer that cannot be captured still scrubs: the window hears it.
    }
    window.addEventListener("pointermove", onPointerMove, true);
    window.addEventListener("pointerup", onPointerUp, true);
    window.addEventListener("pointercancel", onPointerCancel, true);
    window.addEventListener("blur", onBlur);
    document.addEventListener("keydown", onKeyDown, true);
    document.addEventListener("pointerlockchange", onLockChange);
  }

  function onPointerMove(event: PointerEvent): void {
    if (press === null || event.pointerId !== press.pointer) return;
    if (!press.active) {
      if (Math.abs(event.clientX - press.x) < SCRUB_THRESHOLD) return;
      press.active = true;
      scrubbed = true;
      // Counted from here, so that crossing the threshold is not itself a jump.
      press.x = event.clientX;
      press.sign = getComputedStyle(element).direction === "rtl" ? -1 : 1;
      element.dataset.scrubbing = "";
      options().onScrubStart?.();
      // A pen and a finger are where they point; only a mouse can be held in place.
      if (event.pointerType === "mouse") lock();
      return;
    }
    // A locked pointer does not move: it reports how far it would have.
    press.locked ||= document.pointerLockElement === element;
    const moved = press.locked ? event.movementX : event.clientX - press.x;
    press.x = event.clientX;
    const { distance } = options();
    const travel = scrubTravel(press.rest, moved * press.sign, distance);
    press.rest = travel.rest;
    if (travel.steps !== 0) options().onScrub(travel.steps, scrubSize(event));
  }

  function lock(): void {
    if (typeof element.requestPointerLock !== "function") return;
    try {
      // A promise in some engines, nothing in others; refused in either way.
      const asked = element.requestPointerLock() as Promise<void> | undefined;
      asked?.catch?.(() => undefined);
    } catch {
      // Never required: the drag goes on as far as the screen does.
    }
  }

  function onLockChange(): void {
    if (press === null) return;
    const locked = document.pointerLockElement === element;
    // The browser gives the lock up on Escape, and keeps the key to itself.
    if (press.locked && !locked) finish("cancel");
    else press.locked = locked;
  }

  function onPointerUp(event: PointerEvent): void {
    if (event.pointerId !== press?.pointer) return;
    finish("end");
    // Its click, if it has one, follows at once: a later one is somebody's own.
    setTimeout(() => {
      scrubbed = false;
    });
  }

  function onPointerCancel(event: PointerEvent): void {
    if (event.pointerId === press?.pointer) finish("cancel");
  }

  function onBlur(): void {
    finish("cancel");
  }

  function onKeyDown(event: KeyboardEvent): void {
    if (event.key !== "Escape" || press === null || !press.active) return;
    // The scrub's, and no one else's: a popover around the field stays open.
    event.preventDefault();
    event.stopPropagation();
    finish("cancel");
  }

  function onClick(event: MouseEvent): void {
    if (!scrubbed) return;
    scrubbed = false;
    // The release of a drag is not a click: a label would give its field focus.
    event.preventDefault();
    event.stopPropagation();
  }

  element.addEventListener("pointerdown", onPointerDown);
  element.addEventListener("mousedown", onMouseDown);
  element.addEventListener("click", onClick, true);

  return () => {
    finish("end");
    element.removeEventListener("pointerdown", onPointerDown);
    element.removeEventListener("mousedown", onMouseDown);
    element.removeEventListener("click", onClick, true);
    style.cursor = before.cursor;
    style.touchAction = before.touchAction;
    style.userSelect = before.userSelect;
    style.setProperty("-webkit-user-select", before.webkitUserSelect);
    delete element.dataset.scrub;
  };
}

/**
 * A ref for what scrubs — an element of one's own, as `ref`, or one found in
 * the document, called with it. It is the same ref for the life of the
 * component, and hears the options of the latest render.
 */
export function useScrub(options: ScrubOptions): (element: HTMLElement | null) => (() => void) | undefined {
  const latest = useRef(options);
  useLayoutEffect(() => {
    latest.current = options;
  });
  return useCallback(
    (element: HTMLElement | null) => (element === null ? undefined : scrub(element, () => latest.current)),
    [],
  );
}