@tremolo-ui/dom 0.5.0 → 0.6.0

package/src/pointer/{dragValue.ts → drag-value.ts}

@@ -3,6 +3,7 @@ import {
   linearScale,
   normalizeValue,
   stepValue,
+  toPrecision,
   type ValueRange,
 } from '@tremolo-ui/functions'
 
@@ -59,7 +60,32 @@ export interface DragValueMapping {
  */
 export function elementMapping(
   getElement: () => Element | null | undefined,
+  {
+    sensitivity,
+  }: {
+    /**
+     * How much the movement counts, read on every move. `1` is the pointer
+     * position itself; `0.1` makes the same movement cover a tenth of the
+     * travel, which is what a fine-adjustment modifier wants.
+     *
+     * Anything but `1` turns the mapping relative: the value stops being the
+     * position pointed at and starts being where it stood when the sensitivity
+     * changed, plus the movement since. **The pointer and the value stay apart
+     * for the rest of the drag** rather than snapping back together when the
+     * key is released, since snapping would move the value nobody asked to
+     * move.
+     */
+    sensitivity?: (state: DragState) => number
+  } = {},
 ): DragValueMapping {
+  /** The reported position when the sensitivity last changed. */
+  let origin: XY<number> = [0, 0]
+  /** The raw position at that same moment. */
+  let anchor: XY<number> = [0, 0]
+  /** The previous event, so a sensitivity change can be dated back to it. */
+  let previous: XY<number> = [0, 0]
+  let factor = 1
+
   function positionIn(state: DragState): XY<number> | null {
     const element = getElement()
     if (!element) return null
@@ -72,7 +98,48 @@ export function elementMapping(
     ]
   }
 
-  return { start: positionIn, move: positionIn }
+  const reported = (raw: XY<number>, at: number): XY<number> => [
+    origin[0] + (raw[0] - anchor[0]) * at,
+    origin[1] + (raw[1] - anchor[1]) * at,
+  ]
+
+  return {
+    start: (state) => {
+      const raw = positionIn(state)
+      if (!raw) return null
+      // origin and anchor together, so the value is the position pointed at:
+      // a plain click still lands where it was aimed.
+      origin = raw
+      anchor = raw
+      previous = raw
+      // Read here too, so a modifier already held when the pointer went down
+      // applies from the first pixel rather than from the first change.
+      factor = sensitivity ? sensitivity(state) : 1
+      return raw
+    },
+    move: (state) => {
+      const raw = positionIn(state)
+      if (!raw) return null
+
+      const next = sensitivity ? sensitivity(state) : 1
+      if (next !== factor) {
+        // Fold the travel so far into the origin, or the new sensitivity would
+        // apply to the whole drag and the value would jump.
+        //
+        // Dated to the previous event rather than this one: a key produces no
+        // pointer event of its own, so the change is only seen on the next
+        // move, and that move's own distance belongs to the new sensitivity.
+        origin = reported(previous, factor)
+        anchor = previous
+        factor = next
+      }
+      previous = raw
+
+      // With no sensitivity given, origin and anchor never move apart and this
+      // is the raw position, exactly as before.
+      return reported(raw, factor)
+    },
+  }
 }
 
 /**
@@ -82,27 +149,65 @@ export function elementMapping(
  */
 export function relativeMapping({
   pixelRange = 100,
+  sensitivity,
 }: {
   /**
    * Pixels of movement that span the whole range.
    * @default 100
    */
   pixelRange?: XYInput<number>
+  /**
+   * How much the movement counts, read on every move. `1` is `pixelRange` as
+   * given; `0.1` makes the same movement cover a tenth of the range, which is
+   * what a fine-adjustment modifier wants.
+   *
+   * Changing it mid-drag does not disturb the value: the travel so far is
+   * folded into the origin and measuring starts again from there.
+   */
+  sensitivity?: (state: DragState) => number
 } = {}): DragValueMapping {
-  const [rangeX, rangeY] = toXY(pixelRange)
+  const [baseX, baseY] = toXY(pixelRange)
   let origin: XY<number> = [0, 0]
+  /** Where the current sensitivity took over, in drag coordinates. */
+  let anchor: XY<number> = [0, 0]
+  /** The previous event, so a sensitivity change can be dated back to it. */
+  let previous: XY<number> = [0, 0]
+  let factor = 1
+
+  const travelled = (to: XY<number>, at: number): XY<number> => [
+    baseX === 0 ? origin[0] : origin[0] + ((to[0] - anchor[0]) * at) / baseX,
+    baseY === 0 ? origin[1] : origin[1] + ((to[1] - anchor[1]) * at) / baseY,
+  ]
 
   return {
-    start: (_state, context) => {
+    start: (state, context) => {
       origin = context.position()
+      anchor = [0, 0]
+      previous = [0, 0]
+      // Read here too, so a modifier already held when the pointer went down
+      // applies from the first pixel rather than from the first change.
+      factor = sensitivity ? sensitivity(state) : 1
       return origin
     },
-    // `x` and `y` are measured from the start of the drag, so the position
-    // never accumulates a rounding error of its own.
-    move: (state) => [
-      origin[0] + state.x / rangeX,
-      origin[1] + state.y / rangeY,
-    ],
+    // Measured from the anchor rather than accumulated per event, so the
+    // position picks up no rounding error of its own. The anchor only moves
+    // when the sensitivity does, which is a handful of times per drag at most.
+    move: (state) => {
+      const next = sensitivity ? sensitivity(state) : 1
+      if (next !== factor) {
+        // Fold the travel so far into the origin, or the new sensitivity would
+        // apply to the whole drag and the value would jump.
+        //
+        // Dated to the previous event rather than this one: a key produces no
+        // pointer event of its own, so the change is only seen on the next
+        // move, and that move's own distance belongs to the new sensitivity.
+        origin = travelled(previous, factor)
+        anchor = previous
+        factor = next
+      }
+      previous = [state.x, state.y]
+      return travelled([state.x, state.y], factor)
+    },
   }
 }
 
@@ -135,6 +240,16 @@ export interface DragValueOptions {
   threshold?: number
   /** @see DragOptions.cursor */
   cursor?: string
+  /**
+   * @see DragOptions.pointerLock
+   *
+   * Only for a mapping that moves the value relative to where it stood, such
+   * as {@link relativeMapping}. {@link elementMapping} reads the pointer
+   * position, and there is none while it is locked.
+   */
+  pointerLock?: boolean
+  /** @see DragOptions.shouldStart */
+  shouldStart?: (event: PointerEvent) => boolean
 
   onChange?: (value: XY<number>, state: DragState) => void
   onDragStart?: (value: XY<number>, state: DragState) => void
@@ -165,6 +280,7 @@ export function createDragValue(
 ): DragValueInstance {
   let opts = options
   let lastValue: XY<number> = [0, 0]
+  let active = false
 
   const axes = () => toXY(opts.axis)
 
@@ -175,8 +291,9 @@ export function createDragValue(
       const scale = axis.scale ?? linearScale
       const value = scale.denormalize(p, axis.min, axis.max)
       const stepped = axis.step ? stepValue(value, axis.step) : value
-      // Rounding to the step can leave the range.
-      return clamp(stepped, axis.min, axis.max)
+      // Rounding to the step can leave the range, and so can dropping the
+      // binary artefact, so the clamp comes last.
+      return clamp(toPrecision(stepped), axis.min, axis.max)
     }) as XY<number>
   }
 
@@ -200,29 +317,48 @@ export function createDragValue(
   const drag = createDrag(element, {
     threshold: opts.threshold,
     cursor: opts.cursor,
+    pointerLock: opts.pointerLock,
+    shouldStart: (event) => opts.shouldStart?.(event) ?? true,
     onDragStart: (state) => {
       const position = opts.mapping.start(state, context)
-      if (position) {
-        lastValue = valueOf(position)
-        if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state)
-      }
+      if (!position) return
+      active = true
+      lastValue = valueOf(position)
+      if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state)
       opts.onDragStart?.(lastValue, state)
     },
     onDrag: (state) => {
+      if (!active) return
       const position = opts.mapping.move(state, context)
       if (!position) return
       lastValue = valueOf(position)
       opts.onChange?.(lastValue, state)
     },
-    // The pointer has not moved since the last reported value, so `lastValue`
-    // is where the drag ended.
-    onDragEnd: (state) => opts.onDragEnd?.(lastValue, state),
+    onDragEnd: (state) => {
+      if (!active) return
+      if (
+        state.event.type === 'pointerup' &&
+        (state.deltaX !== 0 || state.deltaY !== 0)
+      ) {
+        const position = opts.mapping.move(state, context)
+        if (position) {
+          lastValue = valueOf(position)
+          opts.onChange?.(lastValue, state)
+        }
+      }
+      active = false
+      opts.onDragEnd?.(lastValue, state)
+    },
   })
 
   return {
     update: (next) => {
       opts = { ...opts, ...next, mapping: opts.mapping }
-      drag.update({ threshold: opts.threshold, cursor: opts.cursor })
+      drag.update({
+        threshold: opts.threshold,
+        cursor: opts.cursor,
+        pointerLock: opts.pointerLock,
+      })
     },
     destroy: () => drag.destroy(),
   }

package/src/pointer/drag.ts

@@ -38,6 +38,42 @@ export type DragOptions = {
    */
   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
@@ -52,6 +88,10 @@ export type DragOptions = {
 
   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
 }
 
@@ -64,6 +104,7 @@ export interface DragInstance {
    * here.
    */
   update: (options: DragOptions) => void
+  /** End any active drags before removing the instance. */
   destroy: () => void
 }
 
@@ -81,7 +122,15 @@ 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
@@ -95,6 +144,21 @@ type PointerState = {
   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
 }
 
 /**
@@ -117,11 +181,21 @@ export function createDrag(
   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)
     }
   }
 
@@ -133,6 +207,10 @@ export function createDrag(
    */
   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,
@@ -141,8 +219,14 @@ export function createDrag(
     deltaY: number,
   ): DragState {
     return {
-      x: event.screenX - pointer.startX,
-      y: event.screenY - pointer.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,
@@ -167,6 +251,9 @@ export function createDrag(
       target.addEventListener('pointermove', handlePointerMove)
       target.addEventListener('pointerup', handlePointerUp)
       target.addEventListener('pointercancel', handlePointerUp)
+      if (target === element) {
+        target.addEventListener('lostpointercapture', handleLostPointerCapture)
+      }
     }
     targets.set(target, count + 1)
   }
@@ -180,16 +267,22 @@ export function createDrag(
     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
+    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
 
+    if (opts.shouldStart && !opts.shouldStart(pointerEvent)) return
+
     const isFirst = pointers.size === 0
     if (isFirst && opts.cursor && style) {
       previousCursor = style.cursor
@@ -210,6 +303,9 @@ export function createDrag(
       startY: pointerEvent.screenY,
       lastX: pointerEvent.screenX,
       lastY: pointerEvent.screenY,
+      lockMoveX: 0,
+      lockMoveY: 0,
+      lastEvent: pointerEvent,
     }
     pointers.set(pointerId, pointer)
 
@@ -218,6 +314,38 @@ export function createDrag(
       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))
   }
 
@@ -226,8 +354,15 @@ export function createDrag(
     const pointer = pointers.get(pointerEvent.pointerId)
     if (!pointer) return
 
-    const deltaX = pointerEvent.screenX - pointer.lastX
-    const deltaY = pointerEvent.screenY - pointer.lastY
+    // 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 accumulates until it crosses it. Dropping it
     // instead would swallow a slow drag entirely: pointer coordinates are
@@ -237,20 +372,62 @@ export function createDrag(
 
     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
-    const pointer = pointers.get(pointerEvent.pointerId)
+    finishDrag(pointerEvent.pointerId, pointerEvent)
+  }
+
+  function handleLostPointerCapture(event: Event) {
+    const pointerEvent = event as PointerEvent
+    finishDrag(pointerEvent.pointerId)
+  }
+
+  function finishDrag(pointerId: number, event?: PointerEvent) {
+    const pointer = pointers.get(pointerId)
     if (!pointer) return
 
-    const deltaX = pointerEvent.screenX - pointer.lastX
-    const deltaY = pointerEvent.screenY - pointer.lastY
-    const finalState = state(pointerEvent, pointer, deltaX, deltaY)
+    const finalState = event
+      ? state(
+          event,
+          pointer,
+          event.screenX - pointer.lastX,
+          event.screenY - pointer.lastY,
+        )
+      : state(pointer.lastEvent, pointer, 0, 0)
 
-    stopTracking(pointerEvent.pointerId)
+    stopTracking(pointerId)
     opts.onDragEnd?.(finalState)
   }
 
@@ -258,9 +435,24 @@ export function createDrag(
     const pointer = pointers.get(pointerId)
     if (!pointer) return
 
-    capture.releasePointerCapture?.(pointerId)
-    releaseTarget(pointer.moveTarget)
     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
 
@@ -278,17 +470,20 @@ export function createDrag(
       opts = { ...opts, ...next, multiPointer }
     },
     destroy: () => {
-      for (const pointerId of [...pointers.keys()]) stopTracking(pointerId)
+      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,6 @@
 export interface WheelOptions {
+  /** Replace the callback through {@link WheelInstance.update}. */
+  onWheel?: (event: WheelEvent) => void
   /**
    * Only report events while the focus is inside the element.
    *
@@ -32,7 +34,7 @@ export function createWheel(
   onWheel: (event: WheelEvent) => void,
   options: WheelOptions = {},
 ): WheelInstance {
-  let opts = options
+  let opts = { ...options, onWheel }
 
   function hasFocus() {
     const active = element.ownerDocument?.activeElement
@@ -41,7 +43,7 @@ export function createWheel(
 
   const handler = (event: Event) => {
     if (opts.requireFocus && !hasFocus()) return
-    onWheel(event as WheelEvent)
+    opts.onWheel?.(event as WheelEvent)
   }
 
   element.addEventListener('wheel', handler, { passive: false })