@tremolo-ui/react 0.5.0 → 0.6.0

package/src/hooks/useMIDIAccess.ts

@@ -1,32 +1,103 @@
 import { useEffect, useMemo, useSyncExternalStore } from 'react'
 
-import { createMIDIAccess } from '@tremolo-ui/dom'
+import {
+  createMIDIAccess,
+  type MIDIAccessInstance,
+  type MIDIAccessOptions,
+  type MIDIAccessState,
+} from '@tremolo-ui/dom'
 
 export {
   NOT_SUPPORTED,
   PERMISSION_DENIED,
+  UNAVAILABLE,
   type MIDIAccessError,
+  type MIDIAccessOptions,
 } from '@tremolo-ui/dom'
 
+const INITIAL_STATE: MIDIAccessState = {
+  midiAccess: null,
+  error: null,
+  inputs: [],
+}
+
+function createMIDIAccessStore() {
+  let instance: MIDIAccessInstance | null = null
+  let unsubscribe: VoidFunction | null = null
+  let state = INITIAL_STATE
+  const listeners = new Set<VoidFunction>()
+
+  function emit() {
+    for (const listener of listeners) listener()
+  }
+
+  function connect() {
+    const nextInstance = createMIDIAccess()
+    instance = nextInstance
+    state = nextInstance.getState()
+    unsubscribe = nextInstance.subscribe(() => {
+      state = nextInstance.getState()
+      emit()
+    })
+    emit()
+    return nextInstance
+  }
+
+  function disconnect(currentInstance: MIDIAccessInstance) {
+    if (instance !== currentInstance) return
+
+    unsubscribe?.()
+    unsubscribe = null
+    instance = null
+    state = INITIAL_STATE
+    currentInstance.destroy()
+    emit()
+  }
+
+  function request(options?: MIDIAccessOptions) {
+    instance?.request(options)
+  }
+
+  return {
+    connect,
+    disconnect,
+    request,
+    getState: () => state,
+    getServerState: () => INITIAL_STATE,
+    subscribe: (listener: VoidFunction) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+}
+
 /**
  * Hooks for requesting MIDI access in the browser. The first argument allows you to choose whether to request access on mount.
+ *
+ * `inputs` follows the devices: it changes as one is plugged in or unplugged,
+ * so a list of devices needs no `statechange` listener of its own.
+ *
+ * `request` takes `{ sysex: true }` when the app needs system exclusive
+ * messages. Browsers treat that as a separate, more sensitive permission, so
+ * ask for it only when it is actually used.
  */
 export function useMIDIAccess(requestOnMount = true) {
-  const instance = useMemo(() => createMIDIAccess(), [])
+  const store = useMemo(() => createMIDIAccessStore(), [])
 
-  const { midiAccess, error } = useSyncExternalStore(
-    instance.subscribe,
-    instance.getState,
-    instance.getServerState,
+  const { midiAccess, error, inputs } = useSyncExternalStore(
+    store.subscribe,
+    store.getState,
+    store.getServerState,
   )
 
   useEffect(() => {
-    if (requestOnMount) instance.request()
-  }, [instance, requestOnMount])
+    const instance = store.connect()
+    return () => store.disconnect(instance)
+  }, [store])
 
   useEffect(() => {
-    return () => instance.destroy()
-  }, [instance])
+    if (requestOnMount) store.request()
+  }, [store, requestOnMount])
 
-  return { request: instance.request, midiAccess, error }
+  return { request: store.request, midiAccess, error, inputs }
 }

package/src/hooks/useMIDIInput.ts

@@ -1,22 +1,54 @@
-import { useEffect } from 'react'
+import { useEffect, useRef } from 'react'
 
-import { createMIDIInput } from '@tremolo-ui/dom'
+import {
+  createMIDIInput,
+  PITCH_BEND_CENTER,
+  type MIDIInputHandlers,
+  type MIDIInputInstance,
+} from '@tremolo-ui/dom'
+
+export { PITCH_BEND_CENTER, type MIDIInputHandlers }
 
 /**
- * Hooks for handling note on/off events. To be used with useMIDIAccess. Internally uses useMIDIMessage.
+ * Handle MIDI input events. To be used with {@link useMIDIAccess}.
+ *
+ * The handlers are read fresh on every event, so writing them inline is fine:
+ * the listeners are attached once per `midiAccess` and stay attached. Devices
+ * plugged in later are picked up without anything having to be rebuilt.
+ *
+ * @example
+ * const { midiAccess } = useMIDIAccess()
+ * useMIDIInput(midiAccess, {
+ *   onNoteOnEvent: (note, velocity) => play(note, velocity / 127),
+ *   onNoteOffEvent: (note) => stop(note),
+ *   onControlChangeEvent: (controller, value) => {
+ *     if (controller === 1) setModulation(value / 127)
+ *   },
+ * })
  */
 export function useMIDIInput(
   midiAccess: MIDIAccess | null,
-  onNoteOnEvent?: (note: number, velocity: number) => void,
-  onNoteOffEvent?: (note: number) => void,
-  onPitchBendEvent?: (msb: number, lsb: number) => void,
+  handlers: MIDIInputHandlers,
 ) {
+  // Read when the instance is created. The effect below keeps it current, and
+  // runs right after, so a stale handler is replaced within the same commit.
+  const latest = useRef(handlers)
+  const instanceRef = useRef<MIDIInputInstance | null>(null)
+
+  useEffect(() => {
+    const instance = createMIDIInput(midiAccess, latest.current)
+    instanceRef.current = instance
+
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+    }
+  }, [midiAccess])
+
+  // Runs after every render: handlers come from props and are cheap to push,
+  // and updating in place leaves the listeners untouched.
   useEffect(() => {
-    const instance = createMIDIInput(midiAccess, {
-      onNoteOnEvent,
-      onNoteOffEvent,
-      onPitchBendEvent,
-    })
-    return () => instance.destroy()
-  }, [midiAccess, onNoteOnEvent, onNoteOffEvent, onPitchBendEvent])
+    latest.current = handlers
+    instanceRef.current?.update(handlers)
+  })
 }

package/src/hooks/useMIDIMessage.ts

@@ -1,16 +1,34 @@
-import { useEffect } from 'react'
+import { useEffect, useRef } from 'react'
 
-import { createMIDIMessage } from '@tremolo-ui/dom'
+import { createMIDIMessage, type MIDIMessageInstance } from '@tremolo-ui/dom'
 
 /**
  * Hooks for when you want to process MIDI events in more detail than useMIDIInput.
+ *
+ * The handler is read fresh on every event, so writing it inline is fine: the
+ * listeners are attached once per `midiAccess` and stay attached, and devices
+ * plugged in later are picked up.
  */
 export function useMIDIMessage(
   midiAccess: MIDIAccess | null,
   onMIDIMessage: (event: MIDIMessageEvent) => void,
 ) {
+  const latest = useRef(onMIDIMessage)
+  const instanceRef = useRef<MIDIMessageInstance | null>(null)
+
+  useEffect(() => {
+    const instance = createMIDIMessage(midiAccess, (event) =>
+      latest.current(event),
+    )
+    instanceRef.current = instance
+
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+    }
+  }, [midiAccess])
+
   useEffect(() => {
-    const instance = createMIDIMessage(midiAccess, onMIDIMessage)
-    return () => instance.destroy()
-  }, [midiAccess, onMIDIMessage])
+    latest.current = onMIDIMessage
+  })
 }

package/src/index.ts

@@ -1,31 +1,31 @@
-// For bundled CSS (@tremolo-ui/react/styles/index.css)
-import './styles/global.css'
-import './components/Knob/index.css'
-import './components/NumberInput/index.css'
-import './components/Piano/index.css'
-import './components/PointsEditor/index.css'
-import './components/Slider/index.css'
-import './components/XYPad/index.css'
-
 export {
   AnimationCanvas,
-  type AbsoluteSizingProps,
+  type AnimationCanvasCommonProps,
+  type AnimationCanvasFixedProps,
   type AnimationCanvasProps,
-  type CommonProps,
+  type AnimationCanvasResizableProps,
   type DrawFunction,
   type InitFunction,
-  type RelativeSizingProps,
 } from './components/AnimationCanvas'
-export { Knob, type KnobProps, type KnobMethods } from './components/Knob'
+export {
+  Knob,
+  useKnobContext,
+  type KnobContextValue,
+  type KnobProps,
+  type KnobMethods,
+  type KnobSVGRootProps,
+  type KnobThumbProps,
+} from './components/Knob'
 export {
   NumberInput,
   useNumberInputContext,
+  type NumberInputContextValue,
   type NumberInputProps,
   type NumberInputMethods,
-  type NumberInputFieldProps,
-  type StepperProps,
-  type IncrementStepperProps,
-  type DecrementStepperProps,
+  type NumberInputInputFieldProps,
+  type NumberInputStepperProps,
+  type NumberInputIncrementStepperProps,
+  type NumberInputDecrementStepperProps,
 } from './components/NumberInput'
 export {
   Piano,
@@ -45,14 +45,17 @@ export {
   type PointsEditorContextValue,
   type PointsEditorBackgroundProps,
   type PointsEditorContainerProps,
-  type PointProps,
+  type PointsEditorSelectionBoxProps,
+  type PointsEditorPointProps,
   type PointBaseType,
 } from './components/PointsEditor'
 export {
   Slider,
   useSliderContext,
-  type MarksOptionProps,
-  type MarksProps,
+  type SliderContextValue,
+  type SliderMarksOptionProps,
+  type MarksOptions,
+  type SliderMarksProps,
   type SliderMethods,
   type SliderProps,
   type SliderThumbMethods,
@@ -61,6 +64,8 @@ export {
 } from './components/Slider'
 export {
   XYPad,
+  useXYPadContext,
+  type XYPadContextValue,
   type XYPadProps,
   type XYPadMethods,
   type XYPadAreaProps,
@@ -81,8 +86,20 @@ export {
   useMIDIAccess,
   NOT_SUPPORTED,
   PERMISSION_DENIED,
+  UNAVAILABLE,
   type MIDIAccessError,
+  type MIDIAccessOptions,
 } from './hooks/useMIDIAccess'
-export { useMIDIInput } from './hooks/useMIDIInput'
+export {
+  useMIDIInput,
+  PITCH_BEND_CENTER,
+  type MIDIInputHandlers,
+} from './hooks/useMIDIInput'
 export { useMIDIMessage } from './hooks/useMIDIMessage'
 export { useWheel, type UseWheelOptions } from './hooks/useWheel'
+
+export {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+} from './input-event'

package/src/input-event.ts

@@ -0,0 +1,32 @@
+import type { InputEventOption, ModifierValue } from '@tremolo-ui/functions'
+
+/**
+ * The keyboard amount used by Knob, NumberInput, Slider, and XYPad by default:
+ * 1 per press in the units of the value, and 0.1 with shift held. That is one
+ * `step` only while `step` is 1; a coarser `step` rounds 1 straight back, which
+ * `useCheckSteps` warns about.
+ *
+ * A modifier entry is not snapped to `step`, which is what lets the finer
+ * amount move at all — see `applyDelta` in `@tremolo-ui/functions`.
+ */
+export const DEFAULT_KEYBOARD_OPTIONS: ModifierValue<InputEventOption> = {
+  default: ['raw', 1],
+  shift: ['raw', 0.1],
+}
+
+/**
+ * The wheel amount used by Knob, NumberInput, Slider, and XYPad by default.
+ *
+ * Browsers turn shift+wheel into horizontal scrolling, which empties `deltaY`
+ * and fills `deltaX`, so no modifier is bound here.
+ */
+export const DEFAULT_WHEEL_OPTIONS: ModifierValue<InputEventOption> = ['raw', 1]
+
+/**
+ * The drag sensitivity used by value controls by default. Shift makes the
+ * same movement cover a tenth of the range, matching the arrow keys.
+ */
+export const DEFAULT_DRAG_SENSITIVITY: ModifierValue<number> = {
+  default: 1,
+  shift: 0.1,
+}