@tremolo-ui/dom 0.5.0 → 0.7.0

package/src/input/modifiers.ts

@@ -0,0 +1,121 @@
+/**
+ * Options for setting the amount of keyboard and mouse wheel changes.
+ */
+export type InputEventOption = readonly ['normalized' | 'raw', number]
+
+/**
+ * A modifier key that can carry an amount of its own.
+ *
+ * `ctrl` and `meta` are kept apart rather than folded into one "command" key:
+ * a plugin UI that mirrors a desktop host usually wants the same physical key
+ * on every platform, not the platform's own convention.
+ */
+export type Modifier = 'shift' | 'alt' | 'ctrl' | 'meta'
+
+/** The modifier flags of a `WheelEvent` or a `KeyboardEvent`. */
+export interface ModifierState {
+  shiftKey: boolean
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+}
+
+/** One setting per modifier key, with `default` for none of them. */
+type ModifierSetting = number | InputEventOption
+
+export type ModifierMap<T extends ModifierSetting> = { default: T } & Partial<
+  Record<Modifier, T>
+>
+
+/**
+ * A single setting, or one per modifier key.
+ *
+ * @example
+ * ['raw', 1]
+ * { default: ['raw', 1], shift: ['raw', 0.1] }
+ */
+export type ModifierValue<T extends ModifierSetting> = T | ModifierMap<T>
+
+/**
+ * Checked in this order, and the first one that is both held and configured
+ * wins. Fixing an order is what keeps two modifiers held at once from
+ * behaving differently between browsers.
+ */
+const MODIFIER_ORDER = ['meta', 'ctrl', 'alt', 'shift'] as const
+
+const MODIFIER_FLAG = {
+  meta: 'metaKey',
+  ctrl: 'ctrlKey',
+  alt: 'altKey',
+  shift: 'shiftKey',
+} as const satisfies Record<Modifier, keyof ModifierState>
+
+/**
+ * A map is the only form with a `default` key, which is what tells it apart
+ * from a bare setting. Tuples are arrays, so they never match.
+ */
+function isModifierMap<T extends ModifierSetting>(
+  value: ModifierValue<T>,
+): value is ModifierMap<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    'default' in value
+  )
+}
+
+/**
+ * Pick the setting that applies, given the modifier keys being held.
+ *
+ * @example
+ * selectModifier({ default: 1, shift: 0.1 }, event)
+ */
+export function selectModifier<T extends ModifierSetting>(
+  options: ModifierValue<T>,
+  modifiers?: ModifierState,
+): { value: T; modifier: Modifier | null } {
+  if (!isModifierMap(options)) {
+    // TypeScript cannot subtract the map from `ModifierValue<T>` while `T` is
+    // still a type parameter, so the other half has to be spelled out.
+    return { value: options as T, modifier: null }
+  }
+  if (modifiers) {
+    for (const modifier of MODIFIER_ORDER) {
+      const value = options[modifier]
+      // Compared against undefined rather than checked for truthiness: 0 is a
+      // legitimate setting.
+      if (value !== undefined && modifiers[MODIFIER_FLAG[modifier]]) {
+        return { value, modifier }
+      }
+    }
+  }
+  return { value: options.default, modifier: null }
+}
+
+/**
+ * Turn every entry of a setting into another kind of setting, keeping which
+ * modifier each belongs to.
+ *
+ * A drag sensitivity is a number and a keyboard amount is a tuple, but the two
+ * describe the same thing from the caller's side. This carries one over to the
+ * other so that a component can hand a sensitivity to {@link applyDelta}
+ * without unpicking the modifier map itself — which matters, since naming a
+ * modifier is also what takes `step` out of the pipeline.
+ *
+ * @example
+ * mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])
+ * // { default: ['raw', 1], shift: ['raw', 0.1] }
+ */
+export function mapModifier<
+  T extends ModifierSetting,
+  U extends ModifierSetting,
+>(options: ModifierValue<T>, fn: (value: T) => U): ModifierValue<U> {
+  if (!isModifierMap(options)) return fn(options as T)
+  const mapped = { default: fn(options.default) } as ModifierMap<U>
+  for (const modifier of MODIFIER_ORDER) {
+    const value = options[modifier]
+    if (value !== undefined) mapped[modifier] = fn(value)
+  }
+  return mapped
+}

package/src/midi/access.ts

@@ -2,23 +2,48 @@
 export const PERMISSION_DENIED = 'PERMISSION_DENIED'
 /** @private */
 export const NOT_SUPPORTED = 'NOT_SUPPORTED'
+/** @private */
+export const UNAVAILABLE = 'UNAVAILABLE'
 
 /** @private */
-export type MIDIAccessError = typeof PERMISSION_DENIED | typeof NOT_SUPPORTED
+export type MIDIAccessError =
+  | typeof PERMISSION_DENIED
+  | typeof NOT_SUPPORTED
+  | typeof UNAVAILABLE
+
+export type MIDIAccessOptions = {
+  /**
+   * Ask for system exclusive messages as well.
+   *
+   * Browsers treat this as a separate, more sensitive permission, so leave it
+   * off unless the app actually reads or sends sysex.
+   *
+   * @default false
+   */
+  sysex?: boolean
+}
 
 export type MIDIAccessState = {
   readonly midiAccess: MIDIAccess | null
   readonly error: MIDIAccessError | null
+  /**
+   * The inputs currently connected, in the order MIDIAccess lists them.
+   *
+   * Kept up to date as devices are plugged in and unplugged, so a UI listing
+   * the devices does not have to watch `statechange` itself.
+   */
+  readonly inputs: readonly MIDIInput[]
 }
 
 const INITIAL_STATE: MIDIAccessState = {
   midiAccess: null,
   error: null,
+  inputs: [],
 }
 
 export interface MIDIAccessInstance {
   /** Request MIDI access. Safe to call more than once. */
-  request: () => void
+  request: (options?: MIDIAccessOptions) => void
   getState: () => MIDIAccessState
   /** Snapshot for server side rendering. Always the initial state. */
   getServerState: () => MIDIAccessState
@@ -27,6 +52,28 @@ export interface MIDIAccessInstance {
   destroy: () => void
 }
 
+/**
+ * Which of our errors a rejected `requestMIDIAccess()` amounts to.
+ *
+ * The spec names the reasons, and they need telling apart: a user who said no
+ * can say yes on a second ask, while a browser without the API never will.
+ */
+function toError(reason: unknown): MIDIAccessError {
+  const name =
+    typeof reason === 'object' && reason !== null && 'name' in reason
+      ? String((reason as { name: unknown }).name)
+      : ''
+
+  if (name === 'SecurityError' || name === 'NotAllowedError') {
+    return PERMISSION_DENIED
+  }
+  if (name === 'NotSupportedError' || name === 'TypeError') {
+    return NOT_SUPPORTED
+  }
+  // AbortError, InvalidStateError, and anything a browser makes up.
+  return UNAVAILABLE
+}
+
 /**
  * Request MIDI access in the browser.
  *
@@ -36,6 +83,8 @@ export interface MIDIAccessInstance {
 export function createMIDIAccess(): MIDIAccessInstance {
   let state = INITIAL_STATE
   let destroyed = false
+  let access: MIDIAccess | null = null
+  let requestGeneration = 0
   const listeners = new Set<() => void>()
 
   function setState(next: MIDIAccessState) {
@@ -43,22 +92,40 @@ export function createMIDIAccess(): MIDIAccessInstance {
     for (const listener of listeners) listener()
   }
 
-  function request() {
+  /**
+   * A new array every time, so that `useSyncExternalStore` and its equivalents
+   * see the change. The identity of the state object is what they compare.
+   */
+  function readInputs() {
+    return access ? [...access.inputs.values()] : []
+  }
+
+  function handleStateChange(event?: Event) {
+    if (destroyed || !access) return
+    if (event && (event as MIDIConnectionEvent).port?.type === 'output') return
+    setState({ ...state, inputs: readInputs() })
+  }
+
+  function request(options: MIDIAccessOptions = {}) {
     if (destroyed) return
+    const generation = ++requestGeneration
     if (typeof navigator === 'undefined' || !navigator.requestMIDIAccess) {
       setState({ ...state, error: NOT_SUPPORTED })
       return
     }
-    navigator
-      .requestMIDIAccess()
-      .then((access) => {
-        if (destroyed) return
-        setState({ midiAccess: access, error: null })
-      })
-      .catch(() => {
-        if (destroyed) return
-        setState({ ...state, error: PERMISSION_DENIED })
-      })
+    navigator.requestMIDIAccess({ sysex: options.sysex ?? false }).then(
+      (granted) => {
+        if (destroyed || generation !== requestGeneration) return
+        access?.removeEventListener('statechange', handleStateChange)
+        access = granted
+        granted.addEventListener('statechange', handleStateChange)
+        setState({ midiAccess: granted, error: null, inputs: readInputs() })
+      },
+      (reason: unknown) => {
+        if (destroyed || generation !== requestGeneration) return
+        setState({ ...state, error: toError(reason) })
+      },
+    )
   }
 
   return {
@@ -73,6 +140,9 @@ export function createMIDIAccess(): MIDIAccessInstance {
     },
     destroy: () => {
       destroyed = true
+      requestGeneration += 1
+      access?.removeEventListener('statechange', handleStateChange)
+      access = null
       listeners.clear()
     },
   }

package/src/midi/input.ts

@@ -1,43 +1,114 @@
-import { createMIDIMessage, type MIDIMessageInstance } from './message'
+import { createMIDIMessage } from './message'
 
-const MIDI_EVENT_TO_NUMBER = {
-  NOTE_ON: 0x90,
+/** Status byte of each channel message, with the channel nibble cleared. */
+const STATUS = {
   NOTE_OFF: 0x80,
+  NOTE_ON: 0x90,
+  AFTERTOUCH: 0xa0,
+  CONTROL_CHANGE: 0xb0,
+  PROGRAM_CHANGE: 0xc0,
+  CHANNEL_PRESSURE: 0xd0,
   PITCH_BEND: 0xe0,
 }
 
+/**
+ * Centre of the 14-bit pitch bend range: no bend.
+ *
+ * The range is not symmetric — 0 is 8192 below centre and 16383 is 8191 above
+ * — so a wheel at rest reports exactly this rather than half of the maximum.
+ */
+export const PITCH_BEND_CENTER = 8192
+
+/**
+ * Every handler is given the channel last, as 0-15. MIDI channels are written
+ * 1-16 on hardware, so add one before showing it to anyone.
+ */
 export type MIDIInputHandlers = {
-  onNoteOnEvent?: (note: number, velocity: number) => void
-  onNoteOffEvent?: (note: number) => void
-  onPitchBendEvent?: (msb: number, lsb: number) => void
+  onNoteOnEvent?: (note: number, velocity: number, channel: number) => void
+  onNoteOffEvent?: (note: number, channel: number) => void
+  /**
+   * The 14-bit bend, 0-16383, centred at {@link PITCH_BEND_CENTER}.
+   *
+   * The two data bytes are little-endian — the first carries the low 7 bits —
+   * which is the other way round from every other message.
+   */
+  onPitchBendEvent?: (value: number, channel: number) => void
+  /** `controller` is the CC number, `value` is 0-127. */
+  onControlChangeEvent?: (
+    controller: number,
+    value: number,
+    channel: number,
+  ) => void
+  onProgramChangeEvent?: (program: number, channel: number) => void
+  /** Pressure for one held note (polyphonic aftertouch). */
+  onAftertouchEvent?: (note: number, pressure: number, channel: number) => void
+  /** Pressure for the whole channel, sent by keyboards with one sensor. */
+  onChannelPressureEvent?: (pressure: number, channel: number) => void
 }
 
-export type MIDIInputInstance = MIDIMessageInstance
+export interface MIDIInputInstance {
+  /** Replace the handlers, keeping the listeners in place. */
+  update: (handlers: MIDIInputHandlers) => void
+  destroy: () => void
+}
 
 /**
- * Handle note on/off and pitch bend events. To be used with {@link createMIDIAccess}.
- * Internally uses {@link createMIDIMessage}.
+ * Handle the channel voice messages of every connected input. To be used with
+ * {@link createMIDIAccess}. Internally uses {@link createMIDIMessage}, so
+ * devices plugged in later are picked up.
+ *
+ * System messages (clock, sysex, and the rest of `0xf0`-`0xff`) are not
+ * decoded here; reach for {@link createMIDIMessage} for those.
  */
 export function createMIDIInput(
   midiAccess: MIDIAccess | null,
-  { onNoteOnEvent, onNoteOffEvent, onPitchBendEvent }: MIDIInputHandlers,
+  handlers: MIDIInputHandlers,
 ): MIDIInputInstance {
-  return createMIDIMessage(midiAccess, (event) => {
-    if (!event.data) return
-    // event.data[0] ... command
-    // event.data[1] ... note, MSB (Most Significant Byte)
-    // event.data[2] ... velocity, LSB (Least Significant Byte)
-    const kind = event.data[0] & 0xf0
-
-    if (
-      kind == MIDI_EVENT_TO_NUMBER.NOTE_OFF ||
-      (kind == MIDI_EVENT_TO_NUMBER.NOTE_ON && event.data[2] == 0)
-    ) {
-      onNoteOffEvent?.(event.data[1])
-    } else if (kind == MIDI_EVENT_TO_NUMBER.NOTE_ON) {
-      onNoteOnEvent?.(event.data[1], event.data[2])
-    } else if (kind == MIDI_EVENT_TO_NUMBER.PITCH_BEND) {
-      onPitchBendEvent?.(event.data[1], event.data[2])
+  let current = handlers
+
+  const message = createMIDIMessage(midiAccess, (event) => {
+    if (!event.data || event.data.length === 0) return
+
+    const status = event.data[0]
+    // 0xf0 and above are system messages, which carry no channel.
+    if (status >= 0xf0) return
+
+    const kind = status & 0xf0
+    const channel = status & 0x0f
+    const first = event.data[1] ?? 0
+    const second = event.data[2] ?? 0
+
+    switch (kind) {
+      case STATUS.NOTE_OFF:
+        current.onNoteOffEvent?.(first, channel)
+        break
+      case STATUS.NOTE_ON:
+        // A note on with zero velocity is how most devices say note off.
+        if (second === 0) current.onNoteOffEvent?.(first, channel)
+        else current.onNoteOnEvent?.(first, second, channel)
+        break
+      case STATUS.AFTERTOUCH:
+        current.onAftertouchEvent?.(first, second, channel)
+        break
+      case STATUS.CONTROL_CHANGE:
+        current.onControlChangeEvent?.(first, second, channel)
+        break
+      case STATUS.PROGRAM_CHANGE:
+        current.onProgramChangeEvent?.(first, channel)
+        break
+      case STATUS.CHANNEL_PRESSURE:
+        current.onChannelPressureEvent?.(first, channel)
+        break
+      case STATUS.PITCH_BEND:
+        current.onPitchBendEvent?.((second << 7) | first, channel)
+        break
     }
   })
+
+  return {
+    update: (next) => {
+      current = next
+    },
+    destroy: message.destroy,
+  }
 }

package/src/midi/message.ts

@@ -1,30 +1,59 @@
 export interface MIDIMessageInstance {
+  /** Replace the handler, keeping the listeners in place. */
+  update: (onMIDIMessage: (event: MIDIMessageEvent) => void) => void
   destroy: () => void
 }
 
 /**
  * Listen to raw `midimessage` events on every input of a MIDIAccess.
  *
+ * The set of inputs is followed rather than sampled: MIDIAccess fires
+ * `statechange` when a device is plugged in or unplugged, and the listeners
+ * move with it. A keyboard connected after access was granted works without
+ * the caller having to rebuild anything.
+ *
  * Use this when you need more detail than {@link createMIDIInput} provides.
  */
 export function createMIDIMessage(
   midiAccess: MIDIAccess | null,
   onMIDIMessage: (event: MIDIMessageEvent) => void,
 ): MIDIMessageInstance {
-  if (!midiAccess) {
-    return { destroy: () => {} }
-  }
+  let handler = onMIDIMessage
+
+  /** Inputs this instance currently listens on. */
+  const attached = new Set<MIDIInput>()
+
+  const listener = (event: Event) => handler(event as MIDIMessageEvent)
 
-  const inputs = [...midiAccess.inputs.values()]
-  for (const input of inputs) {
-    input.addEventListener('midimessage', onMIDIMessage)
+  function sync() {
+    if (!midiAccess) return
+    const connected = new Set(midiAccess.inputs.values())
+
+    for (const input of connected) {
+      if (attached.has(input)) continue
+      input.addEventListener('midimessage', listener)
+      attached.add(input)
+    }
+    for (const input of [...attached]) {
+      if (connected.has(input)) continue
+      input.removeEventListener('midimessage', listener)
+      attached.delete(input)
+    }
   }
 
+  sync()
+  midiAccess?.addEventListener('statechange', sync)
+
   return {
+    update: (next) => {
+      handler = next
+    },
     destroy: () => {
-      for (const input of inputs) {
-        input.removeEventListener('midimessage', onMIDIMessage)
+      midiAccess?.removeEventListener('statechange', sync)
+      for (const input of attached) {
+        input.removeEventListener('midimessage', listener)
       }
+      attached.clear()
     },
   }
 }

package/src/piano/{input.ts → index.ts}

@@ -1,7 +1,7 @@
-import { noteAt, type PianoLayout } from '@tremolo-ui/functions'
-
 import { createDrag } from '../pointer/drag'
 
+import { noteAt, type PianoLayout } from './layout'
+
 /**
  * What asked for a note to sound.
  *
@@ -99,6 +99,9 @@ export function createPianoInput(
       velocity,
     }: { source?: NoteSource; velocity?: number } = {},
   ) {
+    if (!Number.isInteger(note) || note < 0 || note > 127) {
+      throw new RangeError('note: requirements: an integer from 0 to 127')
+    }
     if (note > (opts.midiMax ?? 127)) return
 
     const sources = held.get(note)
@@ -117,6 +120,9 @@ export function createPianoInput(
     note: number,
     { source = DEFAULT_SOURCE }: { source?: NoteSource } = {},
   ) {
+    if (!Number.isInteger(note) || note < 0 || note > 127) {
+      throw new RangeError('note: requirements: an integer from 0 to 127')
+    }
     const sources = held.get(note)
     if (!sources) return
 
@@ -142,7 +148,7 @@ export function createPianoInput(
 
     if (previous !== undefined) noteOff(previous, { source })
 
-    if (note === null) {
+    if (note === null || note > (opts.midiMax ?? 127)) {
       pointerNotes.delete(pointerId)
     } else {
       pointerNotes.set(pointerId, note)
@@ -166,6 +172,19 @@ export function createPianoInput(
   return {
     update: (next) => {
       opts = { ...opts, ...next }
+
+      const midiMax = opts.midiMax ?? 127
+      const stoppedNotes = activeNotes().filter((note) => note > midiMax)
+      if (stoppedNotes.length === 0) return
+
+      for (const note of stoppedNotes) {
+        held.delete(note)
+        opts.onStopNote?.(note)
+      }
+      for (const [pointerId, note] of pointerNotes) {
+        if (note > midiMax) pointerNotes.delete(pointerId)
+      }
+      opts.onActiveNotesChange?.(activeNotes())
     },
     noteOn,
     noteOff,
@@ -174,12 +193,13 @@ export function createPianoInput(
       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()) {
+      const notes = activeNotes()
+      for (const note of notes) {
         held.delete(note)
         opts.onStopNote?.(note)
       }
       pointerNotes.clear()
-      opts.onActiveNotesChange?.([])
+      if (notes.length > 0) opts.onActiveNotesChange?.([])
     },
   }
 }