@tremolo-ui/dom 0.3.0 → 0.5.0

package/src/piano/input.ts

@@ -0,0 +1,185 @@
+import { noteAt, type PianoLayout } from '@tremolo-ui/functions'
+
+import { createDrag } from '../pointer/drag'
+
+/**
+ * What asked for a note to sound.
+ *
+ * A note stops only once everything that asked for it has let go, so two
+ * fingers on one key, or a key held by both the mouse and a MIDI keyboard,
+ * behave the way they look.
+ *
+ * Pointers use `pointer:<pointerId>`; everything else names its own source.
+ */
+export type NoteSource = string
+
+export interface PianoInputOptions {
+  /** Geometry of the drawn keyboard, used to find the note under a pointer. */
+  layout: PianoLayout
+
+  /**
+   * Let a pointer slide from one key to the next while it is down. With it off,
+   * the key that was pressed keeps sounding until the pointer is released.
+   *
+   * @default true
+   */
+  glissando?: boolean
+
+  /**
+   * Highest note that can sound. Above it a note is refused, whichever source
+   * asks for it.
+   *
+   * @default 127
+   */
+  midiMax?: number
+
+  /** Called when a note starts sounding, not for each source that asks. */
+  onPlayNote?: (note: number, velocity?: number) => void
+  /** Called once the last source holding a note has let go. */
+  onStopNote?: (note: number) => void
+  /** Called whenever {@link PianoInputInstance.activeNotes} would change. */
+  onActiveNotesChange?: (notes: number[]) => void
+}
+
+export interface PianoInputInstance {
+  /**
+   * Replace the given options. Lets a wrapper feed a fresh layout in without
+   * tearing down the listeners, which would abort a drag in progress.
+   */
+  update: (options: Partial<PianoInputOptions>) => void
+
+  /**
+   * Start a note from something other than a pointer: a keyboard shortcut, a
+   * MIDI message, an imperative call.
+   */
+  noteOn: (
+    note: number,
+    options?: { source?: NoteSource; velocity?: number },
+  ) => void
+  /** Release a note held by `source`. */
+  noteOff: (note: number, options?: { source?: NoteSource }) => void
+
+  /** The notes currently sounding, ascending. */
+  activeNotes: () => number[]
+
+  destroy: () => void
+}
+
+const DEFAULT_SOURCE: NoteSource = 'api'
+
+/**
+ * Drive a piano keyboard with pointers, and own what is sounding.
+ *
+ * Every way of playing a note goes through the one instance — pointers here,
+ * keyboard shortcuts and MIDI through {@link PianoInputInstance.noteOn} — so
+ * there is a single answer to what is currently held, and drawing the keys is
+ * left entirely to the wrapper.
+ *
+ * Tracks every pointer at once, so a chord can be played with several fingers.
+ */
+export function createPianoInput(
+  element: Element,
+  options: PianoInputOptions,
+): PianoInputInstance {
+  let opts = options
+
+  /** Which sources are holding each sounding note. */
+  const held = new Map<number, Set<NoteSource>>()
+  /** The note each pointer is currently on. */
+  const pointerNotes = new Map<number, number>()
+
+  function activeNotes(): number[] {
+    return [...held.keys()].sort((a, b) => a - b)
+  }
+
+  function noteOn(
+    note: number,
+    {
+      source = DEFAULT_SOURCE,
+      velocity,
+    }: { source?: NoteSource; velocity?: number } = {},
+  ) {
+    if (note > (opts.midiMax ?? 127)) return
+
+    const sources = held.get(note)
+    if (sources) {
+      // Already sounding: remember the extra holder and leave it alone.
+      sources.add(source)
+      return
+    }
+
+    held.set(note, new Set([source]))
+    opts.onPlayNote?.(note, velocity)
+    opts.onActiveNotesChange?.(activeNotes())
+  }
+
+  function noteOff(
+    note: number,
+    { source = DEFAULT_SOURCE }: { source?: NoteSource } = {},
+  ) {
+    const sources = held.get(note)
+    if (!sources) return
+
+    sources.delete(source)
+    if (sources.size > 0) return
+
+    held.delete(note)
+    opts.onStopNote?.(note)
+    opts.onActiveNotesChange?.(activeNotes())
+  }
+
+  /** The note under a pointer, or null where the pointer is off the keys. */
+  function noteUnder(clientX: number, clientY: number): number | null {
+    const { left, top, height } = element.getBoundingClientRect()
+    return noteAt(clientX - left, clientY - top, height, opts.layout)
+  }
+
+  /** Move a pointer onto a note, releasing whatever it held before. */
+  function movePointer(pointerId: number, note: number | null) {
+    const source = `pointer:${pointerId}`
+    const previous = pointerNotes.get(pointerId)
+    if (previous === note) return
+
+    if (previous !== undefined) noteOff(previous, { source })
+
+    if (note === null) {
+      pointerNotes.delete(pointerId)
+    } else {
+      pointerNotes.set(pointerId, note)
+      noteOn(note, { source })
+    }
+  }
+
+  const drag = createDrag(element, {
+    multiPointer: true,
+    onDragStart: (state) =>
+      movePointer(state.pointerId, noteUnder(state.clientX, state.clientY)),
+    onDrag: (state) => {
+      // Without glissando the pressed key holds until the pointer is released,
+      // so where the pointer wanders to does not matter.
+      if (opts.glissando === false) return
+      movePointer(state.pointerId, noteUnder(state.clientX, state.clientY))
+    },
+    onDragEnd: (state) => movePointer(state.pointerId, null),
+  })
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
+    noteOn,
+    noteOff,
+    activeNotes,
+    destroy: () => {
+      drag.destroy()
+      // Anything still held is released, so a caller that mirrors these
+      // callbacks into a synth is not left with a stuck note.
+      for (const note of activeNotes()) {
+        held.delete(note)
+        opts.onStopNote?.(note)
+      }
+      pointerNotes.clear()
+      opts.onActiveNotesChange?.([])
+    },
+  }
+}

package/src/pointer/drag.ts

@@ -0,0 +1,295 @@
+export type DragState = {
+  /** Total movement from the drag start, in screen coordinates. */
+  x: number
+  y: number
+  /** Movement since the previous event, in screen coordinates. */
+  deltaX: number
+  deltaY: number
+  /** 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. 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.
+   *
+   * @default 0
+   */
+  threshold?: number
+
+  /**
+   * 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
+
+  /**
+   * 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
+  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
+  destroy: () => void
+}
+
+/**
+ * Applied to the element for the lifetime of the instance.
+ *
+ * `touch-action` stops touch dragging from scrolling the page. That alone makes
+ * the browser treat a long press as the start of a text selection, so selection
+ * and the iOS callout are suppressed here too.
+ */
+const MANAGED_STYLES = [
+  ['touch-action', 'none'],
+  ['user-select', 'none'],
+  ['-webkit-user-select', 'none'],
+  ['-webkit-touch-callout', 'none'],
+] as const
+
+type CaptureTarget = {
+  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
+}
+
+/**
+ * Track a pointer drag on an element.
+ *
+ * Uses Pointer Events only, and pointer capture so that the drag keeps working
+ * once the pointer leaves the element. For the lifetime of the instance the
+ * 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,
+  options: DragOptions = {},
+): DragInstance {
+  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>()
+  if (style) {
+    for (const [property, value] of MANAGED_STYLES) {
+      previousStyles.set(property, style.getPropertyValue(property))
+      style.setProperty(property, value)
+    }
+  }
+
+  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
+
+  function state(
+    event: PointerEvent,
+    pointer: PointerState,
+    deltaX: number,
+    deltaY: number,
+  ): DragState {
+    return {
+      x: event.screenX - pointer.startX,
+      y: event.screenY - pointer.startY,
+      deltaX,
+      deltaY,
+      clientX: event.clientX,
+      clientY: event.clientY,
+      pointerId: event.pointerId,
+      event,
+    }
+  }
+
+  /**
+   * `user-select: none` only makes the element's own text unselectable; the
+   * browser still starts a selection on long press and grabs whatever text it
+   * finds nearby. Cancelling the selection outright is what actually stops it.
+   */
+  function preventSelectStart(event: Event) {
+    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)
+    }
+    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)
+    targets.delete(target)
+  }
+
+  function handlePointerDown(event: Event) {
+    const pointerEvent = event as PointerEvent
+    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
+
+    const isFirst = pointers.size === 0
+    if (isFirst && opts.cursor && style) {
+      previousCursor = style.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.
+    const moveTarget =
+      capture.hasPointerCapture?.(pointerId) === true
+        ? element
+        : (globalThis.window ?? element)
+
+    const pointer: PointerState = {
+      moveTarget,
+      startX: pointerEvent.screenX,
+      startY: pointerEvent.screenY,
+      lastX: pointerEvent.screenX,
+      lastY: pointerEvent.screenY,
+    }
+    pointers.set(pointerId, pointer)
+
+    retainTarget(moveTarget)
+    if (isFirst) {
+      globalThis.document?.addEventListener('selectstart', preventSelectStart)
+    }
+
+    opts.onDragStart?.(state(pointerEvent, pointer, 0, 0))
+  }
+
+  function handlePointerMove(event: Event) {
+    const pointerEvent = event as PointerEvent
+    const pointer = pointers.get(pointerEvent.pointerId)
+    if (!pointer) return
+
+    const deltaX = pointerEvent.screenX - pointer.lastX
+    const deltaY = 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
+    // 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
+
+    pointer.lastX = pointerEvent.screenX
+    pointer.lastY = pointerEvent.screenY
+
+    opts.onDrag?.(state(pointerEvent, pointer, deltaX, deltaY))
+  }
+
+  function handlePointerUp(event: Event) {
+    const pointerEvent = event as PointerEvent
+    const pointer = pointers.get(pointerEvent.pointerId)
+    if (!pointer) return
+
+    const deltaX = pointerEvent.screenX - pointer.lastX
+    const deltaY = pointerEvent.screenY - pointer.lastY
+    const finalState = state(pointerEvent, pointer, deltaX, deltaY)
+
+    stopTracking(pointerEvent.pointerId)
+    opts.onDragEnd?.(finalState)
+  }
+
+  function stopTracking(pointerId: number) {
+    const pointer = pointers.get(pointerId)
+    if (!pointer) return
+
+    capture.releasePointerCapture?.(pointerId)
+    releaseTarget(pointer.moveTarget)
+    pointers.delete(pointerId)
+
+    if (pointers.size > 0) return
+
+    globalThis.document?.removeEventListener('selectstart', preventSelectStart)
+    if (previousCursor !== undefined && style) {
+      style.cursor = previousCursor
+      previousCursor = undefined
+    }
+  }
+
+  element.addEventListener('pointerdown', handlePointerDown)
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next, multiPointer }
+    },
+    destroy: () => {
+      for (const pointerId of [...pointers.keys()]) stopTracking(pointerId)
+      element.removeEventListener('pointerdown', handlePointerDown)
+      if (style) {
+        for (const [property] of MANAGED_STYLES) {
+          const previous = previousStyles.get(property)
+          if (previous) {
+            style.setProperty(property, previous)
+          } else {
+            style.removeProperty(property)
+          }
+        }
+      }
+    },
+  }
+}

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(),
+  }
+}