@tremolo-ui/dom 0.4.0 → 0.6.0

package/src/pointer/drag.ts

@@ -8,16 +8,23 @@ export type DragState = {
   /** Pointer position in viewport coordinates. */
   clientX: number
   clientY: number
+  /**
+   * Which pointer this is. Always the same value for one drag; with
+   * {@link DragOptions.multiPointer} it tells concurrent drags apart.
+   */
+  pointerId: number
   event: PointerEvent
 }
 
 export type DragOptions = {
   /**
-   * Minimum movement in pixels before `onDrag` fires.
+   * Minimum movement in pixels before `onDrag` fires. Movement below it is
+   * carried over to the next event rather than discarded, so a slow drag still
+   * reports once it adds up.
+   *
    * Prevents `onDrag` from firing on, for example, a double click.
-   * Values below 1 are clamped to 1.
    *
-   * @default 1
+   * @default 0
    */
   threshold?: number
 
@@ -25,15 +32,79 @@ export type DragOptions = {
    * CSS cursor to show while dragging. Applied to the element itself: pointer
    * capture keeps it in effect even once the pointer leaves the element, so
    * there is no need to touch the document.
+   *
+   * With {@link DragOptions.multiPointer} it is set for the first pointer and
+   * restored once the last one is up.
    */
   cursor?: string
 
+  /**
+   * Decide whether a pointerdown starts a drag at all.
+   *
+   * Checked before anything else — **before the pointer is captured** — so
+   * declining here leaves the whole gesture to whatever else is listening.
+   * Deciding later would be too late: the capture has already been taken from
+   * the element that was going to handle it.
+   *
+   * The use for it is a drag on a container that also holds draggable things
+   * of its own, such as a rubber-band selection that must not begin on top of
+   * one of the objects it would select.
+   */
+  shouldStart?: (event: PointerEvent) => boolean
+
+  /**
+   * Hide the pointer and read its movement directly, instead of following it
+   * around the screen.
+   *
+   * A relative drag — a knob, a stepper — does not care where the pointer is,
+   * only how far it moved, and letting it wander has two costs: the cursor
+   * ends up far from what it is holding, and **the drag stops at the edge of
+   * the screen**, where the operating system pins the pointer and the
+   * coordinates stop changing. A fine drag reaches that edge quickly.
+   *
+   * **Not for a drag whose value is the position pointed at** — anything on
+   * `elementMapping`. `clientX` / `clientY` freeze while the pointer is
+   * locked, so there is no position left to read.
+   *
+   * The request needs a user gesture, which a pointerdown is, but it can still
+   * be refused; the drag then carries on as an ordinary one. Read on
+   * pointerdown, so `update()` reaches the next drag rather than the current.
+   *
+   * @default false
+   */
+  pointerLock?: boolean
+
+  /**
+   * Track every pointer that goes down on the element, rather than only the
+   * first. Each one gets its own `onDragStart` / `onDrag` / `onDragEnd` and
+   * carries its own totals; {@link DragState.pointerId} says which is which.
+   *
+   * Fixed for the lifetime of the instance: switching part way through a drag
+   * has no meaning, so `update()` ignores it.
+   *
+   * @default false
+   */
+  multiPointer?: boolean
+
   onDragStart?: (state: DragState) => void
   onDrag?: (state: DragState) => void
+  /**
+   * Called exactly once for every drag that starts, whether tracking ends by
+   * pointer release, cancellation, capture or lock loss, or destruction.
+   */
   onDragEnd?: (state: DragState) => void
 }
 
 export interface DragInstance {
+  /**
+   * Replace the given options. Lets a wrapper feed fresh handlers in without
+   * tearing down the listeners, which would abort a drag in progress.
+   *
+   * `multiPointer` is fixed for the lifetime of the instance and is ignored
+   * here.
+   */
+  update: (options: DragOptions) => void
+  /** End any active drags before removing the instance. */
   destroy: () => void
 }
 
@@ -51,12 +122,45 @@ const MANAGED_STYLES = [
   ['-webkit-touch-callout', 'none'],
 ] as const
 
+type ManagedStyleState = {
+  count: number
+  previous: Map<string, { value: string; priority: string }>
+}
+
+const managedStyleStates = new WeakMap<Element, ManagedStyleState>()
+
 type CaptureTarget = {
+  requestPointerLock?: () => unknown
   setPointerCapture?: (pointerId: number) => void
   releasePointerCapture?: (pointerId: number) => void
   hasPointerCapture?: (pointerId: number) => boolean
 }
 
+/** What one pointer needs to report its own movement. */
+type PointerState = {
+  /** Where the listeners for this pointer live. */
+  moveTarget: EventTarget
+  startX: number
+  startY: number
+  lastX: number
+  lastY: number
+  /**
+   * Where the travel stood when the pointer lock took effect, and how far it
+   * has moved since. Screen coordinates stop changing under the lock, so from
+   * that point the movement of each event is added up instead.
+   *
+   * The base is taken when the lock engages rather than on pointerdown: the
+   * request is asynchronous, and whatever movement happened while it was in
+   * flight was measured the ordinary way.
+   */
+  lockBaseX?: number
+  lockBaseY?: number
+  lockMoveX: number
+  lockMoveY: number
+  /** The most recent event, to end the drag with when the lock is lost. */
+  lastEvent: PointerEvent
+}
+
 /**
  * Track a pointer drag on an element.
  *
@@ -65,50 +169,69 @@ type CaptureTarget = {
  * element gets `touch-action: none` so that touch dragging does not scroll the
  * page, plus `user-select: none` so that a long press does not start a text
  * selection instead.
+ *
+ * One pointer at a time by default; see {@link DragOptions.multiPointer}.
  */
 export function createDrag(
   element: Element,
-  {
-    threshold: _threshold = 1,
-    cursor,
-    onDragStart,
-    onDrag,
-    onDragEnd,
-  }: DragOptions = {},
+  options: DragOptions = {},
 ): DragInstance {
-  const threshold = Math.max(_threshold, 1)
+  let opts = options
+  const multiPointer = options.multiPointer ?? false
   const capture = element as CaptureTarget
   const style = (element as Partial<HTMLElement>).style
 
-  const previousStyles = new Map<string, string>()
+  let managedStyles = managedStyleStates.get(element)
   if (style) {
-    for (const [property, value] of MANAGED_STYLES) {
-      previousStyles.set(property, style.getPropertyValue(property))
-      style.setProperty(property, value)
+    if (managedStyles) {
+      managedStyles.count += 1
+    } else {
+      const previous = new Map<string, { value: string; priority: string }>()
+      for (const [property, value] of MANAGED_STYLES) {
+        previous.set(property, {
+          value: style.getPropertyValue(property),
+          priority: style.getPropertyPriority(property),
+        })
+        style.setProperty(property, value)
+      }
+      managedStyles = { count: 1, previous }
+      managedStyleStates.set(element, managedStyles)
     }
   }
 
-  let pointerId: number | null = null
-  /** Where the listeners for the current drag live. */
-  let moveTarget: EventTarget | null = null
-  let startX = 0
-  let startY = 0
-  let lastX = 0
-  let lastY = 0
+  const pointers = new Map<number, PointerState>()
+  /**
+   * How many pointers each target carries. Adding the same listener twice is a
+   * no-op and removing it once removes it for good, so a target is subscribed
+   * to while at least one pointer is on it and no longer.
+   */
+  const targets = new Map<EventTarget, number>()
   let previousCursor: string | undefined
+  /** The pointer that asked for the lock, while it is still down. */
+  let lockedPointerId: number | null = null
+  let lockRequest = 0
+  let destroyed = false
 
   function state(
     event: PointerEvent,
+    pointer: PointerState,
     deltaX: number,
     deltaY: number,
   ): DragState {
     return {
-      x: event.screenX - startX,
-      y: event.screenY - startY,
+      x:
+        pointer.lockBaseX !== undefined
+          ? pointer.lockBaseX + pointer.lockMoveX
+          : event.screenX - pointer.startX,
+      y:
+        pointer.lockBaseY !== undefined
+          ? pointer.lockBaseY + pointer.lockMoveY
+          : event.screenY - pointer.startY,
       deltaX,
       deltaY,
       clientX: event.clientX,
       clientY: event.clientY,
+      pointerId: event.pointerId,
       event,
     }
   }
@@ -122,93 +245,245 @@ export function createDrag(
     event.preventDefault()
   }
 
+  function retainTarget(target: EventTarget) {
+    const count = targets.get(target) ?? 0
+    if (count === 0) {
+      target.addEventListener('pointermove', handlePointerMove)
+      target.addEventListener('pointerup', handlePointerUp)
+      target.addEventListener('pointercancel', handlePointerUp)
+      if (target === element) {
+        target.addEventListener('lostpointercapture', handleLostPointerCapture)
+      }
+    }
+    targets.set(target, count + 1)
+  }
+
+  function releaseTarget(target: EventTarget) {
+    const count = targets.get(target) ?? 0
+    if (count > 1) {
+      targets.set(target, count - 1)
+      return
+    }
+    target.removeEventListener('pointermove', handlePointerMove)
+    target.removeEventListener('pointerup', handlePointerUp)
+    target.removeEventListener('pointercancel', handlePointerUp)
+    if (target === element) {
+      target.removeEventListener('lostpointercapture', handleLostPointerCapture)
+    }
+    targets.delete(target)
+  }
+
   function handlePointerDown(event: Event) {
     const pointerEvent = event as PointerEvent
-    // Only one pointer drives the drag; ignore additional touches.
-    if (pointerId !== null) return
+    if (pointerEvent.button !== 0) return
+    const pointerId = pointerEvent.pointerId
+    // Without multiPointer only one pointer drives the drag; ignore the rest.
+    if (pointers.has(pointerId)) return
+    if (!multiPointer && pointers.size > 0) return
 
-    pointerId = pointerEvent.pointerId
-    startX = lastX = pointerEvent.screenX
-    startY = lastY = pointerEvent.screenY
+    if (opts.shouldStart && !opts.shouldStart(pointerEvent)) return
 
-    if (cursor && style) {
+    const isFirst = pointers.size === 0
+    if (isFirst && opts.cursor && style) {
       previousCursor = style.cursor
-      style.cursor = cursor
+      style.cursor = opts.cursor
     }
 
     capture.setPointerCapture?.(pointerId)
     // With pointer capture the element receives the rest of the gesture.
     // Without it (older engines, jsdom) fall back to the window.
-    moveTarget =
+    const moveTarget =
       capture.hasPointerCapture?.(pointerId) === true
         ? element
         : (globalThis.window ?? element)
 
-    moveTarget.addEventListener('pointermove', handlePointerMove)
-    moveTarget.addEventListener('pointerup', handlePointerUp)
-    moveTarget.addEventListener('pointercancel', handlePointerUp)
-    globalThis.document?.addEventListener('selectstart', preventSelectStart)
+    const pointer: PointerState = {
+      moveTarget,
+      startX: pointerEvent.screenX,
+      startY: pointerEvent.screenY,
+      lastX: pointerEvent.screenX,
+      lastY: pointerEvent.screenY,
+      lockMoveX: 0,
+      lockMoveY: 0,
+      lastEvent: pointerEvent,
+    }
+    pointers.set(pointerId, pointer)
 
-    onDragStart?.(state(pointerEvent, 0, 0))
+    retainTarget(moveTarget)
+    if (isFirst) {
+      globalThis.document?.addEventListener('selectstart', preventSelectStart)
+    }
+
+    // One pointer can be locked, so the first one takes it.
+    if (isFirst && opts.pointerLock) {
+      const requestId = ++lockRequest
+      lockedPointerId = pointerId
+      globalThis.document?.addEventListener(
+        'pointerlockchange',
+        handleLockChange,
+      )
+      try {
+        // Newer engines return a promise that rejects; older ones fire
+        // `pointerlockerror` instead. Either way a refusal only means the drag
+        // stays an ordinary one, so nothing here has to act on it.
+        const request = capture.requestPointerLock?.() as
+          | Promise<void>
+          | undefined
+        request?.then?.(
+          () => {
+            if (
+              requestId === lockRequest &&
+              (!pointers.has(pointerId) || destroyed) &&
+              globalThis.document?.pointerLockElement === element
+            ) {
+              globalThis.document.exitPointerLock?.()
+            }
+          },
+          () => {},
+        )
+      } catch {
+        // requestPointerLock threw synchronously; same story.
+      }
+    }
+
+    opts.onDragStart?.(state(pointerEvent, pointer, 0, 0))
   }
 
   function handlePointerMove(event: Event) {
     const pointerEvent = event as PointerEvent
-    if (pointerEvent.pointerId !== pointerId) return
+    const pointer = pointers.get(pointerEvent.pointerId)
+    if (!pointer) return
 
-    const deltaX = pointerEvent.screenX - lastX
-    const deltaY = pointerEvent.screenY - lastY
-    lastX = pointerEvent.screenX
-    lastY = pointerEvent.screenY
+    // Under the lock the screen position no longer moves, so the movement the
+    // event reports is the only thing left to read.
+    const locked = pointer.lockBaseX !== undefined
+    const deltaX = locked
+      ? (pointerEvent.movementX ?? 0)
+      : pointerEvent.screenX - pointer.lastX
+    const deltaY = locked
+      ? (pointerEvent.movementY ?? 0)
+      : pointerEvent.screenY - pointer.lastY
 
-    // Movement below the threshold is dropped rather than accumulated.
+    // Movement below the threshold accumulates until it crosses it. Dropping it
+    // instead would swallow a slow drag entirely: pointer coordinates are
+    // fractional, so each event can move less than a pixel and never report.
+    const threshold = opts.threshold ?? 0
     if (Math.abs(deltaX) < threshold && Math.abs(deltaY) < threshold) return
 
-    onDrag?.(state(pointerEvent, deltaX, deltaY))
+    pointer.lastX = pointerEvent.screenX
+    pointer.lastY = pointerEvent.screenY
+    pointer.lastEvent = pointerEvent
+    if (locked) {
+      pointer.lockMoveX += deltaX
+      pointer.lockMoveY += deltaY
+    }
+
+    opts.onDrag?.(state(pointerEvent, pointer, deltaX, deltaY))
+  }
+
+  function handleLockChange() {
+    if (lockedPointerId === null) return
+    const pointer = pointers.get(lockedPointerId)
+    if (!pointer) return
+
+    if (globalThis.document?.pointerLockElement === element) {
+      // Engaged. Whatever moved while the request was in flight was measured
+      // the ordinary way, so the travel so far becomes the base and the
+      // per-event movement is added to it from here.
+      pointer.lockBaseX = pointer.lastX - pointer.startX
+      pointer.lockBaseY = pointer.lastY - pointer.startY
+      pointer.lockMoveX = 0
+      pointer.lockMoveY = 0
+      return
+    }
+
+    // Lost without the pointer coming up: Esc, a tab switch, leaving
+    // fullscreen. No pointerup is coming, so the drag ends here rather than
+    // hanging on with a pointer nobody can see.
+    if (pointer.lockBaseX === undefined) return
+    finishDrag(lockedPointerId)
   }
 
   function handlePointerUp(event: Event) {
     const pointerEvent = event as PointerEvent
-    if (pointerEvent.pointerId !== pointerId) return
+    finishDrag(pointerEvent.pointerId, pointerEvent)
+  }
+
+  function handleLostPointerCapture(event: Event) {
+    const pointerEvent = event as PointerEvent
+    finishDrag(pointerEvent.pointerId)
+  }
 
-    const deltaX = pointerEvent.screenX - lastX
-    const deltaY = pointerEvent.screenY - lastY
-    const finalState = state(pointerEvent, deltaX, deltaY)
+  function finishDrag(pointerId: number, event?: PointerEvent) {
+    const pointer = pointers.get(pointerId)
+    if (!pointer) return
 
-    stopTracking()
-    onDragEnd?.(finalState)
+    const finalState = event
+      ? state(
+          event,
+          pointer,
+          event.screenX - pointer.lastX,
+          event.screenY - pointer.lastY,
+        )
+      : state(pointer.lastEvent, pointer, 0, 0)
+
+    stopTracking(pointerId)
+    opts.onDragEnd?.(finalState)
   }
 
-  function stopTracking() {
-    if (pointerId === null) return
-    capture.releasePointerCapture?.(pointerId)
-    moveTarget?.removeEventListener('pointermove', handlePointerMove)
-    moveTarget?.removeEventListener('pointerup', handlePointerUp)
-    moveTarget?.removeEventListener('pointercancel', handlePointerUp)
+  function stopTracking(pointerId: number) {
+    const pointer = pointers.get(pointerId)
+    if (!pointer) return
+
+    pointers.delete(pointerId)
+    releaseTarget(pointer.moveTarget)
+    try {
+      if (capture.hasPointerCapture?.(pointerId) === true) {
+        capture.releasePointerCapture?.(pointerId)
+      }
+    } catch {
+      // The capture may disappear between checking and releasing it. Tracking
+      // is already cleared, so the drag still ends normally.
+    }
+
+    if (lockedPointerId === pointerId) {
+      lockedPointerId = null
+      const document = globalThis.document
+      document?.removeEventListener('pointerlockchange', handleLockChange)
+      // Already gone when the lock is what ended the drag.
+      if (document?.pointerLockElement === element) document.exitPointerLock?.()
+    }
+
+    if (pointers.size > 0) return
+
     globalThis.document?.removeEventListener('selectstart', preventSelectStart)
-    if (cursor && style) {
-      style.cursor = previousCursor ?? ''
+    if (previousCursor !== undefined && style) {
+      style.cursor = previousCursor
       previousCursor = undefined
     }
-    moveTarget = null
-    pointerId = null
   }
 
   element.addEventListener('pointerdown', handlePointerDown)
 
   return {
+    update: (next) => {
+      opts = { ...opts, ...next, multiPointer }
+    },
     destroy: () => {
-      stopTracking()
+      if (destroyed) return
+      destroyed = true
       element.removeEventListener('pointerdown', handlePointerDown)
-      if (style) {
+      for (const pointerId of [...pointers.keys()]) finishDrag(pointerId)
+      if (style && managedStyles && --managedStyles.count === 0) {
         for (const [property] of MANAGED_STYLES) {
-          const previous = previousStyles.get(property)
-          if (previous) {
-            style.setProperty(property, previous)
+          const previous = managedStyles.previous.get(property)
+          if (previous?.value) {
+            style.setProperty(property, previous.value, previous.priority)
           } else {
             style.removeProperty(property)
           }
         }
+        managedStyleStates.delete(element)
       }
     },
   }

package/src/pointer/wheel.ts

@@ -1,4 +1,25 @@
+export interface WheelOptions {
+  /** Replace the callback through {@link WheelInstance.update}. */
+  onWheel?: (event: WheelEvent) => void
+  /**
+   * Only report events while the focus is inside the element.
+   *
+   * A control that reacts to the wheel on hover alone takes the scroll away
+   * from the page, so passing over one in a long form silently changes its
+   * value. Requiring focus makes that an explicit act.
+   *
+   * The check is `contains`, not an identity test: the element that actually
+   * takes focus is usually a descendant, such as a thumb or an `<input>`, and
+   * a caller may have replaced it with markup of their own.
+   *
+   * @default false
+   */
+  requireFocus?: boolean
+}
+
 export interface WheelInstance {
+  /** Replace the given options, keeping the listener in place. */
+  update: (options: WheelOptions) => void
   destroy: () => void
 }
 
@@ -11,12 +32,26 @@ export interface WheelInstance {
 export function createWheel(
   element: Element,
   onWheel: (event: WheelEvent) => void,
+  options: WheelOptions = {},
 ): WheelInstance {
-  const handler = (event: Event) => onWheel(event as WheelEvent)
+  let opts = { ...options, onWheel }
+
+  function hasFocus() {
+    const active = element.ownerDocument?.activeElement
+    return !!active && element.contains(active)
+  }
+
+  const handler = (event: Event) => {
+    if (opts.requireFocus && !hasFocus()) return
+    opts.onWheel?.(event as WheelEvent)
+  }
 
   element.addEventListener('wheel', handler, { passive: false })
 
   return {
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
     destroy: () => {
       // Only `capture` matters when removing, and it is false here.
       element.removeEventListener('wheel', handler)