@tremolo-ui/dom 0.7.0 → 0.9.0

package/src/number-input/value.ts

@@ -0,0 +1,129 @@
+import { type Scale, type ValueRange } from '@tremolo-ui/functions'
+
+import { applyDelta } from '../input/apply-delta'
+import {
+  selectModifier,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from '../input/modifiers'
+
+/**
+ * The value a number input edits, and how far it may go.
+ *
+ * Unlike a slider, either end may be left open, and `clampValue: false` lets
+ * the value past the ends that are set.
+ */
+export interface NumberInputValueOptions {
+  min?: number
+  max?: number
+  step?: number
+  scale?: Scale
+  /**
+   * Keep the value between `min` and `max`.
+   *
+   * @default true
+   */
+  clampValue?: boolean
+}
+
+/** The ranges {@link nudgeNumberInput} moves a value across. */
+export interface NumberInputRanges {
+  /** For a `normalized` amount, which needs a finite span to take a share of. */
+  normalized: ValueRange
+  /** For a `raw` amount, which does not. */
+  raw: ValueRange
+}
+
+/**
+ * The ranges a number input moves its value across, with the open ends
+ * filled in.
+ *
+ * A normalized amount needs a finite span even when an end is unbounded or
+ * clamping is off. Safe integers provide one without overflowing the span a
+ * scale calculates. A raw amount needs no span, so its open ends can cover
+ * every finite number instead of stopping at the safe-integer range.
+ */
+export function numberInputRanges({
+  min,
+  max,
+  step,
+  scale,
+  clampValue = true,
+}: NumberInputValueOptions): NumberInputRanges {
+  const lo = clampValue ? min : undefined
+  const hi = clampValue ? max : undefined
+  return {
+    normalized: {
+      min: lo ?? Number.MIN_SAFE_INTEGER,
+      max: hi ?? Number.MAX_SAFE_INTEGER,
+      step,
+      scale,
+    },
+    raw: {
+      min: lo ?? -Number.MAX_VALUE,
+      max: hi ?? Number.MAX_VALUE,
+      step,
+      scale,
+    },
+  }
+}
+
+/**
+ * Move a number input's value by one press of a key, a wheel notch or a
+ * stepper, picking the range that suits the kind of amount. See `applyDelta`.
+ */
+export function nudgeNumberInput(
+  value: number,
+  direction: number,
+  options: ModifierValue<InputEventOption>,
+  ranges: NumberInputRanges,
+  modifiers?: ModifierState,
+): number {
+  const [mode] = selectModifier(options, modifiers).value
+  return applyDelta(
+    value,
+    direction,
+    options,
+    mode === 'raw' ? ranges.raw : ranges.normalized,
+    modifiers,
+  )
+}
+
+/**
+ * Where the value stands against the ends: whether it can go no further
+ * down or up, and whether it lies outside them — which only an unclamped
+ * input, or a value set from outside, can do.
+ */
+export function numberInputBounds(
+  value: number,
+  { min, max, clampValue = true }: NumberInputValueOptions,
+) {
+  return {
+    atMin: clampValue && min !== undefined && value <= min,
+    atMax: clampValue && max !== undefined && value >= max,
+    outOfRange:
+      (min !== undefined && value < min) || (max !== undefined && value > max),
+  }
+}
+
+/**
+ * The value typed text commits to, or `null` when there is no number in it.
+ *
+ * Text with no number is not a value: the input should go back to what it
+ * was showing rather than commit a zero the user never typed. What is read
+ * is clamped here and not while typing, since clamping as the user types
+ * would make "1500" impossible to enter into an input whose max is 100.
+ */
+export function commitNumberInputText(
+  text: string,
+  parse: (text: string) => number,
+  { min, max, clampValue = true }: NumberInputValueOptions,
+): number | null {
+  const parsed = parse(text)
+  if (!Number.isFinite(parsed)) return null
+  let committed = parsed
+  if (clampValue && min !== undefined) committed = Math.max(committed, min)
+  if (clampValue && max !== undefined) committed = Math.min(committed, max)
+  return committed
+}

package/src/options/replace.ts

@@ -0,0 +1,22 @@
+/**
+ * The `update()` argument that leaves an instance with exactly `next` as its
+ * options.
+ *
+ * `update()` merges into what the instance has, which suits a wrapper that
+ * pushes one setting at a time. A wrapper handed the whole new set instead —
+ * a Svelte action, a Vue composable — has to clear what the new set no longer
+ * carries, or a handler taken away, or an option left to its default, keeps
+ * working.
+ *
+ * @example
+ * instance.update(replaceOptions(previous, next))
+ */
+export function replaceOptions<T extends object>(
+  previous: T | undefined,
+  next: T | undefined,
+): Partial<T> {
+  const cleared = Object.fromEntries(
+    Object.keys(previous ?? {}).map((key) => [key, undefined]),
+  ) as Partial<T>
+  return { ...cleared, ...next }
+}

package/src/piano/index.ts

@@ -1,6 +1,11 @@
 import { createDrag } from '../pointer/drag'
 
 import { noteAt, type PianoLayout } from './layout'
+import {
+  isEditableTarget,
+  type KeyboardShortcuts,
+  type KeyboardShortcutsScope,
+} from './shortcuts'
 
 /**
  * What asked for a note to sound.
@@ -33,6 +38,26 @@ export interface PianoInputOptions {
    */
   midiMax?: number
 
+  /**
+   * Play notes from the computer keyboard: `keys[i]` plays
+   * `layout.noteRange.first + i`. `SHORTCUTS` has ready-made layouts.
+   *
+   * A held key keeps its note until it is released, the focus leaves (with
+   * `root`), or the window loses focus. Changing the keys, the scope or the
+   * note range releases every note a key is holding, since the key would
+   * mean something else on release.
+   */
+  keyboardShortcuts?: KeyboardShortcuts
+
+  /**
+   * Where keyboard shortcuts listen: on the element (`root`), which has to
+   * be focusable, or anywhere on the page (`window`). Keys typed into an
+   * editable element are ignored either way.
+   *
+   * @default 'root'
+   */
+  keyboardShortcutsScope?: KeyboardShortcutsScope
+
   /** 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. */
@@ -49,8 +74,8 @@ export interface PianoInputInstance {
   update: (options: Partial<PianoInputOptions>) => void
 
   /**
-   * Start a note from something other than a pointer: a keyboard shortcut, a
-   * MIDI message, an imperative call.
+   * Start a note from something other than a pointer or a shortcut: a MIDI
+   * message, an imperative call.
    */
   noteOn: (
     note: number,
@@ -87,6 +112,11 @@ export function createPianoInput(
   const held = new Map<number, Set<NoteSource>>()
   /** The note each pointer is currently on. */
   const pointerNotes = new Map<number, number>()
+  /**
+   * The note each held shortcut key is playing, by `code` — the physical key,
+   * so that releasing it with a different modifier or layout still matches.
+   */
+  const shortcutNotes = new Map<string, number>()
 
   function activeNotes(): number[] {
     return [...held.keys()].sort((a, b) => a - b)
@@ -156,6 +186,97 @@ export function createPianoInput(
     }
   }
 
+  /** The note a shortcut key plays, or null when it has none. */
+  function shortcutNote(key: string) {
+    const keys = opts.keyboardShortcuts?.keys
+    if (!keys || key === '') return null
+    const { first, last } = opts.layout.noteRange
+    const index = keys.indexOf(key)
+    const note = first + index
+    return index === -1 || note > last ? null : note
+  }
+
+  function onKeyDown(event: KeyboardEvent) {
+    const id = event.code || event.key
+    if (event.repeat || shortcutNotes.has(id)) return
+    if (isEditableTarget(event.target)) return
+    const note = shortcutNote(event.key)
+    if (note === null) return
+    shortcutNotes.set(id, note)
+    noteOn(note, { source: `keyboard:${id}` })
+  }
+
+  function onKeyUp(event: KeyboardEvent) {
+    const id = event.code || event.key
+    const note = shortcutNotes.get(id)
+    if (note === undefined) return
+    shortcutNotes.delete(id)
+    noteOff(note, { source: `keyboard:${id}` })
+  }
+
+  function releaseShortcuts() {
+    for (const [id, note] of shortcutNotes) {
+      noteOff(note, { source: `keyboard:${id}` })
+    }
+    shortcutNotes.clear()
+  }
+
+  function onFocusOut(event: Event) {
+    const next = (event as FocusEvent).relatedTarget
+    // Moving between the keys and whatever else is inside keeps them held.
+    if (next instanceof Node && element.contains(next)) return
+    releaseShortcuts()
+  }
+
+  /** The scope the listeners are bound for, or null when none are. */
+  let boundScope: KeyboardShortcutsScope | null = null
+
+  function bindShortcuts() {
+    const scope = opts.keyboardShortcuts
+      ? (opts.keyboardShortcutsScope ?? 'root')
+      : null
+    if (scope === boundScope) return
+    unbindShortcuts()
+    const win = globalThis.window
+    if (!scope || !win) return
+    const target: EventTarget = scope === 'window' ? win : element
+    target.addEventListener('keydown', onKeyDown as EventListener)
+    target.addEventListener('keyup', onKeyUp as EventListener)
+    if (scope === 'root') element.addEventListener('focusout', onFocusOut)
+    // A key released while the window is in the background never sends its
+    // keyup, so everything is let go when the focus leaves the page.
+    win.addEventListener('blur', releaseShortcuts)
+    boundScope = scope
+  }
+
+  function unbindShortcuts() {
+    const win = globalThis.window
+    if (!boundScope || !win) return
+    const target: EventTarget = boundScope === 'window' ? win : element
+    target.removeEventListener('keydown', onKeyDown as EventListener)
+    target.removeEventListener('keyup', onKeyUp as EventListener)
+    element.removeEventListener('focusout', onFocusOut)
+    win.removeEventListener('blur', releaseShortcuts)
+    boundScope = null
+  }
+
+  /**
+   * What the held keys were started against. Compared by value: a caller
+   * who writes the keys inline hands over a new array on every update, and
+   * releasing on that would stop a note as soon as anything re-renders.
+   */
+  function shortcutMapping() {
+    const { first, last } = opts.layout.noteRange
+    return [
+      opts.keyboardShortcuts?.keys.join('\u0000') ?? '',
+      opts.keyboardShortcutsScope ?? 'root',
+      first,
+      last,
+    ].join('\u0001')
+  }
+
+  bindShortcuts()
+
   const drag = createDrag(element, {
     multiPointer: true,
     onDragStart: (state) =>
@@ -171,7 +292,10 @@ export function createPianoInput(
 
   return {
     update: (next) => {
+      const mapping = shortcutMapping()
       opts = { ...opts, ...next }
+      if (shortcutMapping() !== mapping) releaseShortcuts()
+      bindShortcuts()
 
       const midiMax = opts.midiMax ?? 127
       const stoppedNotes = activeNotes().filter((note) => note > midiMax)
@@ -191,6 +315,8 @@ export function createPianoInput(
     activeNotes,
     destroy: () => {
       drag.destroy()
+      unbindShortcuts()
+      shortcutNotes.clear()
       // Anything still held is released, so a caller that mirrors these
       // callbacks into a synth is not left with a stuck note.
       const notes = activeNotes()

package/src/piano/layout.ts

@@ -181,3 +181,22 @@ export function noteAt(
 
   return null
 }
+
+/**
+ * The white key width that makes the keyboard exactly `width` wide, for a
+ * keyboard that follows the size of its container.
+ *
+ * Solved from {@link pianoWidth} rather than by dividing among the white
+ * keys, so that a range that starts or ends on a black key — which sticks out
+ * by a fraction of a white key — still fills the container. The width grows
+ * linearly with the white key width, so two samples pin it down.
+ */
+export function fitWhiteKeyWidth(
+  width: number,
+  layout: Omit<PianoLayout, 'whiteKeyWidth'>,
+): number {
+  const at = (whiteKeyWidth: number) => pianoWidth({ ...layout, whiteKeyWidth })
+  const slope = at(2) - at(1)
+  if (slope <= 0) return 0
+  return (width - (at(1) - slope)) / slope
+}

package/src/piano/shortcuts.ts

@@ -0,0 +1,86 @@
+export type KeyboardShortcuts = {
+  /**
+   * Keys laid out from `noteRange.first`, one entry per semitone.
+   *
+   * An empty string leaves that note without a shortcut: `KeyboardEvent.key` is
+   * never empty, so the entry can never match. Use it to skip the black keys
+   * (see {@link SHORTCUTS.HOME_ROW_NATURAL}) and keep the remaining entries
+   * lined up with the notes.
+   */
+  keys: string[]
+}
+
+/**
+ * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
+ */
+export const SHORTCUTS = {
+  /** Every semitone from C, over the two rows of a QWERTY keyboard. */
+  HOME_ROW: {
+    keys: [
+      'a',
+      'w',
+      's',
+      'e',
+      'd',
+      'f',
+      't',
+      'g',
+      'y',
+      'h',
+      'u',
+      'j',
+      'k',
+      'o',
+      'l',
+      'p',
+      ';',
+    ],
+  },
+  /** The white keys only, on the home row. Black keys have no shortcut. */
+  HOME_ROW_NATURAL: {
+    keys: [
+      'a',
+      '',
+      's',
+      '',
+      'd',
+      'f',
+      '',
+      'g',
+      '',
+      'h',
+      '',
+      'j',
+      'k',
+      '',
+      'l',
+      '',
+      ';',
+    ],
+  },
+}
+
+/**
+ * Where keyboard shortcuts listen. `root` handles keys only while the piano
+ * or one of its descendants has focus; `window` handles them anywhere on the
+ * page except in editable elements.
+ */
+export type KeyboardShortcutsScope = 'root' | 'window'
+
+/**
+ * Whether a key press was typed into something: shortcuts must not play a
+ * note for a letter that is going into a text field.
+ */
+export function isEditableTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false
+  if (target.matches('input, textarea, select')) return true
+
+  for (let element: HTMLElement | null = target; element;) {
+    const contentEditable = element.getAttribute('contenteditable')
+    if (contentEditable !== null)
+      return contentEditable.toLowerCase() !== 'false'
+    element = element.parentElement
+  }
+
+  return false
+}

package/src/pointer/drag-value.ts

@@ -324,8 +324,10 @@ export function createDragValue(
       if (!position) return
       active = true
       lastValue = valueOf(position)
-      if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state)
+      // Reported before the value it pressed: whoever records the drag hears
+      // that it began before the first value of it arrives.
       opts.onDragStart?.(lastValue, state)
+      if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state)
     },
     onDrag: (state) => {
       if (!active) return

package/src/pointer/long-press.ts

@@ -0,0 +1,103 @@
+export interface LongPressOptions {
+  /** Called once on the press, then again every `interval` after `delay`. */
+  onPress: () => void
+  /**
+   * How long the press has to be held before it starts repeating, in
+   * milliseconds.
+   *
+   * @default 500
+   */
+  delay?: number
+  /**
+   * How often it repeats once it has started, in milliseconds.
+   *
+   * @default 40
+   */
+  interval?: number
+}
+
+export interface LongPressInstance {
+  /**
+   * Start a press, from a `pointerdown` or with no event at all. Only the
+   * primary button starts one, and a press already in progress is left alone.
+   */
+  start: (event?: Pick<PointerEvent, 'button' | 'pointerId'>) => void
+  /** End the press, as releasing the pointer would. */
+  stop: () => void
+  /** Replace the given options. The press in progress picks them up. */
+  update: (options: Partial<LongPressOptions>) => void
+  /** Whether a press is in progress. */
+  pressed: () => boolean
+  destroy: () => void
+}
+
+/**
+ * Repeat an action while a pointer is held down: once on the press, then
+ * again every `interval` after `delay` — the way a stepper button or a
+ * key held on a keyboard behaves.
+ *
+ * The release is listened for on the window, not on the element: the
+ * pointer may be let go anywhere. Only the pointer that started the press
+ * ends it, so a second finger lifting elsewhere does not. The window losing
+ * focus ends it too, since the release would never arrive.
+ */
+export function createLongPress(options: LongPressOptions): LongPressInstance {
+  let opts = options
+  let pointerId: number | null = null
+  let active = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  function clearTimer() {
+    if (timer !== null) clearTimeout(timer)
+    timer = null
+  }
+
+  /** Wait `wait`, fire, and keep going at `interval` from then on. */
+  function schedule(wait: number) {
+    timer = setTimeout(() => {
+      opts.onPress()
+      if (active) schedule(opts.interval ?? 40)
+    }, wait)
+  }
+
+  function onPointerEnd(event: PointerEvent) {
+    // Pointer events carry an id; a press started without one ends on any.
+    if (pointerId !== null && event.pointerId !== pointerId) return
+    stop()
+  }
+
+  function listen(add: boolean) {
+    const target = globalThis.window
+    if (!target) return
+    const method = add ? 'addEventListener' : 'removeEventListener'
+    target[method]('pointerup', onPointerEnd as EventListener)
+    target[method]('pointercancel', onPointerEnd as EventListener)
+    target[method]('blur', stop)
+  }
+
+  function stop() {
+    if (!active) return
+    active = false
+    pointerId = null
+    clearTimer()
+    listen(false)
+  }
+
+  return {
+    start: (event) => {
+      if (active || (event && event.button !== 0)) return
+      active = true
+      pointerId = event?.pointerId ?? null
+      listen(true)
+      opts.onPress()
+      // The action may have stopped the press itself.
+      if (active) schedule(opts.delay ?? 500)
+    },
+    stop,
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
+    pressed: () => active,
+    destroy: stop,
+  }
+}

package/src/pointer/wheel.ts

@@ -1,6 +1,10 @@
 export interface WheelOptions {
-  /** Replace the callback through {@link WheelInstance.update}. */
-  onWheel?: (event: WheelEvent) => void
+  /**
+   * Called for every wheel event that `requireFocus` lets through. The
+   * listener is not passive, so this may call `preventDefault()` to keep the
+   * page from scrolling.
+   */
+  onWheel: (event: WheelEvent) => void
   /**
    * Only report events while the focus is inside the element.
    *
@@ -19,7 +23,7 @@ export interface WheelOptions {
 
 export interface WheelInstance {
   /** Replace the given options, keeping the listener in place. */
-  update: (options: WheelOptions) => void
+  update: (options: Partial<WheelOptions>) => void
   destroy: () => void
 }
 
@@ -31,10 +35,9 @@ export interface WheelInstance {
  */
 export function createWheel(
   element: Element,
-  onWheel: (event: WheelEvent) => void,
-  options: WheelOptions = {},
+  options: WheelOptions,
 ): WheelInstance {
-  let opts = { ...options, onWheel }
+  let opts = options
 
   function hasFocus() {
     const active = element.ownerDocument?.activeElement
@@ -43,7 +46,7 @@ export function createWheel(
 
   const handler = (event: Event) => {
     if (opts.requireFocus && !hasFocus()) return
-    opts.onWheel?.(event as WheelEvent)
+    opts.onWheel(event as WheelEvent)
   }
 
   element.addEventListener('wheel', handler, { passive: false })