@tremolo-ui/dom 0.4.0 → 0.5.0

package/src/pointer/dragValue.ts

@@ -0,0 +1,229 @@
+import {
+  clamp,
+  linearScale,
+  normalizeValue,
+  stepValue,
+  type ValueRange,
+} from '@tremolo-ui/functions'
+
+import { toXY, type XY, type XYInput } from '../xy'
+
+import { createDrag, type DragState } from './drag'
+
+/**
+ * How the 0-1 travel of one axis maps onto a value.
+ *
+ * Extends `ValueRange` so that a drag and an `applyDelta` nudge from a wheel
+ * or an arrow key share one description of the scaling.
+ */
+export interface AxisOptions extends ValueRange {
+  /**
+   * Flip the axis so that its far end is `min`.
+   *
+   * Positions follow the screen: x grows to the right, y downwards. A vertical
+   * slider whose maximum is at the top therefore reverses its y axis.
+   *
+   * @default false
+   */
+  reverse?: boolean
+}
+
+/** Where the value of each axis currently sits, as a position (see {@link DragValueMapping}). */
+export interface MappingContext {
+  position: () => XY<number>
+}
+
+/**
+ * Turns pointer movement into a position on each axis: 0 is the `min` end of
+ * the travel and 1 the `max` end, before `reverse` and the scaling of
+ * {@link AxisOptions} are applied.
+ *
+ * A mapping holds the state of the drag in progress, so an instance belongs to
+ * a single {@link createDragValue} instance.
+ */
+export interface DragValueMapping {
+  /**
+   * @returns the position, or null when it cannot be determined and the event
+   * should be ignored.
+   */
+  start: (state: DragState, context: MappingContext) => XY<number> | null
+  move: (state: DragState, context: MappingContext) => XY<number> | null
+}
+
+/**
+ * Map the pointer onto the bounding rect of an element: the value *is* the
+ * position pointed at, so the middle of the element is 0.5.
+ *
+ * The element is read on every event, so it may be mounted after the drag is
+ * set up and may change size while a drag is in progress.
+ */
+export function elementMapping(
+  getElement: () => Element | null | undefined,
+): DragValueMapping {
+  function positionIn(state: DragState): XY<number> | null {
+    const element = getElement()
+    if (!element) return null
+    const { left, top, right, bottom } = element.getBoundingClientRect()
+    // A collapsed element has no travel to normalize against, and
+    // normalizeValue rejects an empty range.
+    return [
+      right > left ? normalizeValue(state.clientX, left, right) : 0,
+      bottom > top ? normalizeValue(state.clientY, top, bottom) : 0,
+    ]
+  }
+
+  return { start: positionIn, move: positionIn }
+}
+
+/**
+ * Move the value away from where it stood when the drag started, by the
+ * distance dragged. The pointer position itself carries no meaning, so the
+ * value can be adjusted from anywhere on the screen.
+ */
+export function relativeMapping({
+  pixelRange = 100,
+}: {
+  /**
+   * Pixels of movement that span the whole range.
+   * @default 100
+   */
+  pixelRange?: XYInput<number>
+} = {}): DragValueMapping {
+  const [rangeX, rangeY] = toXY(pixelRange)
+  let origin: XY<number> = [0, 0]
+
+  return {
+    start: (_state, context) => {
+      origin = context.position()
+      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,
+    ],
+  }
+}
+
+export interface DragValueOptions {
+  /** Scaling of each axis; a single value applies to both. */
+  axis: XYInput<AxisOptions>
+
+  /** How pointer movement becomes a position. */
+  mapping: DragValueMapping
+
+  /**
+   * The current value of each axis. Read when a drag starts, by mappings that
+   * move the value relative to it, such as {@link relativeMapping}.
+   */
+  getValue?: () => XY<number>
+
+  /**
+   * Report the value on pointer down, before any movement.
+   *
+   * Enable it where the pointer position *is* the value, so that a plain click
+   * jumps to it. Leave it off where the element being dragged is an object in
+   * its own right, so that grabbing its edge does not shift it under the
+   * pointer.
+   *
+   * @default false
+   */
+  updateOnPointerDown?: boolean
+
+  /** @see DragOptions.threshold */
+  threshold?: number
+  /** @see DragOptions.cursor */
+  cursor?: string
+
+  onChange?: (value: XY<number>, state: DragState) => void
+  onDragStart?: (value: XY<number>, state: DragState) => void
+  onDragEnd?: (value: XY<number>, state: DragState) => void
+}
+
+export interface DragValueInstance {
+  /**
+   * Replace the given options. Lets a wrapper feed fresh values in without
+   * tearing down the listeners, which would abort a drag in progress.
+   *
+   * `mapping` is fixed for the lifetime of the instance and is ignored here.
+   */
+  update: (options: Partial<DragValueOptions>) => void
+  destroy: () => void
+}
+
+/**
+ * Drive a value with a pointer drag.
+ *
+ * Combines {@link createDrag} with the scaling of `@tremolo-ui/functions`: the
+ * mapping decides where the pointer sits on the 0-1 travel of each axis, and
+ * the axis options turn that into a value.
+ */
+export function createDragValue(
+  element: Element,
+  options: DragValueOptions,
+): DragValueInstance {
+  let opts = options
+  let lastValue: XY<number> = [0, 0]
+
+  const axes = () => toXY(opts.axis)
+
+  function valueOf(position: XY<number>): XY<number> {
+    return axes().map((axis, i) => {
+      const p = axis.reverse ? 1 - position[i] : position[i]
+      // A scale clamps the position, so a mapping may report outside 0-1.
+      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)
+    }) as XY<number>
+  }
+
+  const context: MappingContext = {
+    position: () => {
+      const getValue = opts.getValue
+      if (!getValue) {
+        throw new Error(
+          'createDragValue: getValue is required by the given mapping',
+        )
+      }
+      const value = getValue()
+      return axes().map((axis, i) => {
+        const scale = axis.scale ?? linearScale
+        const n = scale.normalize(value[i], axis.min, axis.max)
+        return axis.reverse ? 1 - n : n
+      }) as XY<number>
+    },
+  }
+
+  const drag = createDrag(element, {
+    threshold: opts.threshold,
+    cursor: opts.cursor,
+    onDragStart: (state) => {
+      const position = opts.mapping.start(state, context)
+      if (position) {
+        lastValue = valueOf(position)
+        if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state)
+      }
+      opts.onDragStart?.(lastValue, state)
+    },
+    onDrag: (state) => {
+      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),
+  })
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next, mapping: opts.mapping }
+      drag.update({ threshold: opts.threshold, cursor: opts.cursor })
+    },
+    destroy: () => drag.destroy(),
+  }
+}

package/src/pointer/wheel.ts

@@ -1,4 +1,23 @@
+export interface WheelOptions {
+  /**
+   * 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 +30,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
+
+  function hasFocus() {
+    const active = element.ownerDocument?.activeElement
+    return !!active && element.contains(active)
+  }
+
+  const handler = (event: Event) => {
+    if (opts.requireFocus && !hasFocus()) return
+    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)

package/src/xy.ts

@@ -0,0 +1,38 @@
+/**
+ * A pair of per-axis values. The tuple elements are labelled, so editors show
+ * `[x: number, y: number]` rather than a bare pair.
+ */
+export type XY<T> = [x: T, y: T]
+
+/**
+ * A setting that may be given once for both axes, or per axis.
+ *
+ * A single value is told from a pair with `Array.isArray`, so the single form
+ * is only offered while `T` cannot itself be an array. Where it can, the pair
+ * is the only way to write it, since a lone array would be read as a pair.
+ */
+export type XYInput<T> = [T] extends [readonly unknown[]]
+  ? readonly [x: T, y: T]
+  : T | readonly [x: T, y: T]
+
+// `Array.isArray` narrows a mutable tuple on its own, but not a readonly one,
+// hence the explicit predicate.
+function isPair<T>(
+  value: T | readonly [x: T, y: T],
+): value is readonly [x: T, y: T] {
+  return Array.isArray(value)
+}
+
+/**
+ * Spread a setting that may have been given as a single value.
+ *
+ * The parameter is written out rather than taken as `XYInput<T>`: a
+ * conditional type cannot be narrowed, so the constraint stays where it is
+ * declared and this takes both forms.
+ *
+ * The pair is copied rather than passed along, so that the result is a tuple
+ * the caller owns even when a readonly one was given.
+ */
+export function toXY<T>(value: T | readonly [x: T, y: T]): XY<T> {
+  return isPair(value) ? [value[0], value[1]] : [value, value]
+}