@tremolo-ui/dom 0.5.0 → 0.6.0

package/src/canvas/context.ts

@@ -1,7 +1,8 @@
 /**
- * The properties of a 2D context that survive `save()` / `restore()`, and so
- * are what has to be carried across a resize by hand: setting `canvas.width`
- * resets the context to its defaults.
+ * The assignable parts of a 2D context's drawing state. They have to be
+ * carried across a resize by hand because setting `canvas.width` resets the
+ * context to its defaults. The transform and line dash are handled separately
+ * by {@link DrawingContext} because they are exposed through methods.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
  */
@@ -19,20 +20,33 @@ export const drawingState = [
   'shadowBlur',
   'shadowColor',
   'globalCompositeOperation',
+  'filter',
   'font',
+  'fontKerning',
+  'fontStretch',
+  'fontVariantCaps',
   'textAlign',
   'textBaseline',
   'direction',
+  'letterSpacing',
+  'textRendering',
+  'wordSpacing',
   'imageSmoothingEnabled',
+  'imageSmoothingQuality',
 ] as const
 
 export type DrawingState = (typeof drawingState)[number]
 export type DrawingStateValue = CanvasRenderingContext2D[DrawingState]
-export type DrawingContext = Pick<CanvasRenderingContext2D, DrawingState>
+export type DrawingContext = Pick<CanvasRenderingContext2D, DrawingState> & {
+  /** The current line dash sequence. */
+  lineDash: number[]
+  /** The current transformation matrix. */
+  transform: DOMMatrix
+}
 
 export function isDrawingState(value: unknown): value is DrawingState {
   const names: readonly string[] = drawingState
-  return typeof value == 'string' && names.includes(value)
+  return typeof value === 'string' && names.includes(value)
 }
 
 /** Copy the drawing state off a context, to put back after a resize. */
@@ -43,6 +57,8 @@ export function readDrawingState(
   for (const property of drawingState) {
     ;(state[property] as DrawingStateValue) = context[property]
   }
+  state.lineDash = context.getLineDash()
+  state.transform = context.getTransform()
   return state
 }
 
@@ -50,10 +66,21 @@ export function readDrawingState(
 export function writeDrawingState(
   context: CanvasRenderingContext2D,
   state: DrawingContext,
+  transformScale = 1,
 ) {
   for (const property of drawingState) {
     ;(context[property] as DrawingStateValue) = state[property]
   }
+  context.setLineDash(state.lineDash)
+  const { a, b, c, d, e, f } = state.transform
+  context.setTransform(
+    a * transformScale,
+    b * transformScale,
+    c * transformScale,
+    d * transformScale,
+    e * transformScale,
+    f * transformScale,
+  )
 }
 
 /**

package/src/index.ts

@@ -17,12 +17,15 @@ export {
   createMIDIAccess,
   NOT_SUPPORTED,
   PERMISSION_DENIED,
+  UNAVAILABLE,
   type MIDIAccessError,
   type MIDIAccessInstance,
+  type MIDIAccessOptions,
   type MIDIAccessState,
 } from './midi/access'
 export {
   createMIDIInput,
+  PITCH_BEND_CENTER,
   type MIDIInputHandlers,
   type MIDIInputInstance,
 } from './midi/input'
@@ -32,7 +35,7 @@ export {
   type NoteSource,
   type PianoInputInstance,
   type PianoInputOptions,
-} from './piano/input'
+} from './piano'
 export {
   createDrag,
   type DragInstance,
@@ -48,10 +51,18 @@ export {
   type DragValueMapping,
   type DragValueOptions,
   type MappingContext,
-} from './pointer/dragValue'
+} from './pointer/drag-value'
 export {
   createWheel,
   type WheelInstance,
   type WheelOptions,
 } from './pointer/wheel'
+export {
+  createSelectionBox,
+  selectionBoxCovers,
+  type SelectionBoxBeginOptions,
+  type SelectionBoxInstance,
+  type SelectionBoxOptions,
+  type SelectionBoxRect,
+} from './selection/box'
 export { toXY, type XY, type XYInput } from './xy'

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}

@@ -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?.([])
     },
   }
 }