@tremolo-ui/dom 0.5.0 → 0.7.0

package/src/piano/layout.ts

@@ -0,0 +1,183 @@
+import {
+  isBlackKey,
+  isWhiteKey,
+  noteKey,
+  noteKeys,
+  type NoteKey,
+} from '@tremolo-ui/functions'
+
+export type NoteRange = {
+  first: number
+  last: number
+}
+
+/**
+ * `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`
+ */
+export function getNoteRangeArray(noteRange: NoteRange): number[] {
+  return Array.from(
+    { length: noteRange.last - noteRange.first + 1 },
+    (_, i) => i + noteRange.first,
+  )
+}
+
+/**
+ * The geometry of a drawn keyboard.
+ *
+ * One description is shared by the drawing and the hit testing, so a key cannot
+ * be drawn somewhere other than where it responds.
+ */
+export interface PianoLayout {
+  noteRange: NoteRange
+
+  /** Width of a white key, excluding {@link PianoLayout.keyGap}. */
+  whiteKeyWidth: number
+
+  /**
+   * Space between two white keys. Part of the slot a white key occupies, so it
+   * still belongs to one of the keys for the purpose of hit testing.
+   *
+   * @default 1
+   */
+  keyGap?: number
+
+  /**
+   * Width of a black key, as a fraction of {@link PianoLayout.whiteKeyWidth}.
+   *
+   * @default 0.65
+   */
+  blackKeyWidthRatio?: number
+
+  /**
+   * Height of a black key, as a fraction of the height of the keyboard.
+   *
+   * @default 0.6
+   */
+  blackKeyHeightRatio?: number
+}
+
+const DEFAULT_KEY_GAP = 1
+const DEFAULT_BLACK_KEY_WIDTH_RATIO = 0.65
+const DEFAULT_BLACK_KEY_HEIGHT_RATIO = 0.6
+
+/**
+ * How many white keys sit at or before each pitch class, counting from C.
+ *
+ * A black key shares the number of the white key to its left plus one, which
+ * puts it on the boundary between the two; {@link notePosition} then shifts it
+ * back by half its width to centre it there.
+ */
+const whiteKeysBefore: Record<NoteKey, number> = {
+  C: 0,
+  'C#': 1,
+  D: 1,
+  'D#': 2,
+  E: 2,
+  F: 3,
+  'F#': 4,
+  G: 4,
+  'G#': 5,
+  A: 5,
+  'A#': 6,
+  B: 6,
+}
+
+/** Width of a black key in pixels. */
+export function blackKeyWidth(layout: PianoLayout): number {
+  return (
+    layout.whiteKeyWidth *
+    (layout.blackKeyWidthRatio ?? DEFAULT_BLACK_KEY_WIDTH_RATIO)
+  )
+}
+
+function rawNotePosition(note: number, layout: PianoLayout): number {
+  const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)
+  const target = noteKey(note)
+  const first = noteKey(layout.noteRange.first)
+
+  const octave = Math.floor((note - layout.noteRange.first) / 12)
+  const octaveOffset =
+    noteKeys.indexOf(first) > noteKeys.indexOf(target) ? 1 : 0
+  const whiteKeysIn =
+    whiteKeysBefore[target] -
+    whiteKeysBefore[first] +
+    (octave + octaveOffset) * 7
+
+  return isBlackKey(note)
+    ? whiteKeysIn * slot - blackKeyWidth(layout) / 2
+    : whiteKeysIn * slot
+}
+
+function pianoBounds(layout: PianoLayout) {
+  const notes = getNoteRangeArray(layout.noteRange)
+  if (notes.length === 0) return { left: 0, right: 0 }
+
+  let left = Infinity
+  let right = -Infinity
+  const whiteWidth = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)
+  for (const note of notes) {
+    const noteLeft = rawNotePosition(note, layout)
+    const width = isBlackKey(note) ? blackKeyWidth(layout) : whiteWidth
+    left = Math.min(left, noteLeft)
+    right = Math.max(right, noteLeft + width)
+  }
+  return { left, right }
+}
+
+/** Width of the whole keyboard in pixels. */
+export function pianoWidth(layout: PianoLayout): number {
+  const { left, right } = pianoBounds(layout)
+  return right - left
+}
+
+/**
+ * Offset of the left edge of a key from the left edge of the keyboard, in
+ * pixels.
+ *
+ * Notes outside `noteRange` are placed too, so the value is negative below
+ * `noteRange.first`.
+ */
+export function notePosition(note: number, layout: PianoLayout): number {
+  return rawNotePosition(note, layout) - pianoBounds(layout).left
+}
+
+/**
+ * The note drawn at a point, or null where there is none.
+ *
+ * Black keys are tested first, so they win where they overlap a white one. A
+ * white key covers its gap as well as its width, so the whole width of the
+ * keyboard belongs to some key and a click cannot fall between two.
+ *
+ * @param x offset from the left edge of the keyboard, in pixels
+ * @param y offset from its top edge, in pixels
+ * @param height height of the keyboard, in pixels
+ */
+export function noteAt(
+  x: number,
+  y: number,
+  height: number,
+  layout: PianoLayout,
+): number | null {
+  if (x < 0 || x >= pianoWidth(layout) || y < 0 || y >= height) return null
+
+  const notes = getNoteRangeArray(layout.noteRange)
+  const blackHeight =
+    height * (layout.blackKeyHeightRatio ?? DEFAULT_BLACK_KEY_HEIGHT_RATIO)
+
+  if (y < blackHeight) {
+    for (const note of notes) {
+      if (isWhiteKey(note)) continue
+      const left = notePosition(note, layout)
+      if (left <= x && x < left + blackKeyWidth(layout)) return note
+    }
+  }
+
+  const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)
+  for (const note of notes) {
+    if (isBlackKey(note)) continue
+    const left = notePosition(note, layout)
+    if (left <= x && x < left + slot) return note
+  }
+
+  return null
+}

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