@tremolo-ui/react 0.4.0 → 0.6.0

package/src/hooks/useEventListener.ts

@@ -1,6 +1,6 @@
-import { useEffect } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 
-import { useCallbackRef } from './useCallbackRef'
+import { useCallbackRef } from './_internal/useCallbackRef'
 
 type Target = EventTarget | null | (() => EventTarget | null)
 type Options = boolean | AddEventListenerOptions
@@ -30,6 +30,7 @@ export function useEventListener(
   options?: Options,
 ) {
   const listener = useCallbackRef(handler)
+  const cleanupRef = useRef<VoidFunction>(() => {})
 
   useEffect(() => {
     const node = typeof target === 'function' ? target() : (target ?? document)
@@ -37,13 +38,16 @@ export function useEventListener(
     if (!node) return
 
     node.addEventListener(event, listener, options)
-    return () => {
+    const cleanup = () => {
       node.removeEventListener(event, listener, options)
     }
+    cleanupRef.current = cleanup
+
+    return () => {
+      cleanup()
+      if (cleanupRef.current === cleanup) cleanupRef.current = () => {}
+    }
   }, [event, target, options, listener])
 
-  return () => {
-    const node = typeof target === 'function' ? target() : (target ?? document)
-    node?.removeEventListener(event, listener, options)
-  }
+  return useCallback(() => cleanupRef.current(), [])
 }

package/src/hooks/useLongPress.ts

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react'
+import { useCallback, useRef, useState } from 'react'
 
 import { useEventListener } from './useEventListener'
 import { useInterval } from './useInterval'
@@ -10,6 +10,8 @@ export function useLongPress(
 ) {
   const [pressed, setPressed] = useState(false)
   const [delay, setDelay] = useState(initialDelay)
+  const activePointerId = useRef<number | null>(null)
+  const isPressed = useRef(false)
 
   useInterval(
     () => {
@@ -19,13 +21,45 @@ export function useLongPress(
     pressed ? delay : null,
   )
 
-  useEventListener(globalThis.window, 'pointerup', () => {
-    setPressed(false)
-    setDelay(initialDelay)
+  const stop = useCallback(
+    (pointerId?: number) => {
+      if (!isPressed.current) return
+      if (
+        pointerId !== undefined &&
+        activePointerId.current !== null &&
+        activePointerId.current !== pointerId
+      )
+        return
+
+      isPressed.current = false
+      activePointerId.current = null
+      setPressed(false)
+      setDelay(initialDelay)
+    },
+    [initialDelay],
+  )
+
+  useEventListener(globalThis.window, 'pointerup', (event) => {
+    stop(event.pointerId)
+  })
+
+  useEventListener(globalThis.window, 'pointercancel', (event) => {
+    stop(event.pointerId)
   })
 
-  return useCallback(() => {
-    callback()
-    setPressed(true)
-  }, [callback])
+  useEventListener(globalThis.window, 'blur', () => {
+    stop()
+  })
+
+  return useCallback(
+    (event?: Pick<PointerEvent, 'button' | 'pointerId'>) => {
+      if (isPressed.current || (event && event.button !== 0)) return
+
+      isPressed.current = true
+      activePointerId.current = event?.pointerId ?? null
+      callback()
+      setPressed(true)
+    },
+    [callback],
+  )
 }

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/hooks/useWheel.ts

@@ -1,18 +1,35 @@
-import { useEffect, useState } from 'react'
-
-import { createWheel } from '@tremolo-ui/dom'
-
-import { useCallbackRef } from './useCallbackRef'
+import { RefObject, useEffect, useState } from 'react'
+
+import { createWheel, type WheelOptions } from '@tremolo-ui/dom'
+
+import { useCallbackRef } from './_internal/useCallbackRef'
+
+export interface UseWheelOptions extends WheelOptions {
+  /**
+   * Listen on this element rather than on the one the returned ref callback is
+   * attached to, and ignore that callback.
+   *
+   * For a control made of several movable parts: a wheel event only reaches
+   * what the cursor is over, so a listener per part responds only while the
+   * cursor is over that same part. Listening on the element they share lets
+   * every part see the event, and each one decide whether it is the one to act.
+   *
+   * The element is read when the listener is attached, so a ref filled in by a
+   * parent is fine as long as the parent is above in the tree.
+   */
+  target?: RefObject<Element | null>
+}
 
 /**
  * Listen to wheel events on an element.
  *
  * The listener is not passive, so the handler may call `preventDefault()`.
  *
- * @returns a ref callback to attach to the element
+ * @returns a ref callback to attach to the element, unused when `target` is given
  */
 export function useWheel<T extends Element>(
   onWheel: (event: WheelEvent) => void,
+  { requireFocus = false, target }: UseWheelOptions = {},
 ): (node: T | null) => void {
   const wheelHandler = useCallbackRef(onWheel)
 
@@ -20,12 +37,15 @@ export function useWheel<T extends Element>(
   const [node, setNode] = useState<T | null>(null)
 
   useEffect(() => {
-    if (!node) return
+    const element = target ? target.current : node
+    if (!element) return
 
-    const instance = createWheel(node, (event) => wheelHandler(event))
+    const instance = createWheel(element, (event) => wheelHandler(event), {
+      requireFocus,
+    })
 
     return () => instance.destroy()
-  }, [node, wheelHandler])
+  }, [node, target, wheelHandler, requireFocus])
 
   return setNode
 }

package/src/index.ts

@@ -1,53 +1,61 @@
-// 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 StepperProps,
-  type IncrementStepperProps,
-  type DecrementStepperProps,
+  type NumberInputInputFieldProps,
+  type NumberInputStepperProps,
+  type NumberInputIncrementStepperProps,
+  type NumberInputDecrementStepperProps,
 } from './components/NumberInput'
 export {
   Piano,
-  getNoteRangeArray,
   SHORTCUTS,
   type PianoProps,
   type PianoMethods,
-  type KeyProps,
-  type KeyMethods,
-  type KeyLabelProps,
+  type KeyState,
+  type KeyAttributes,
+  type CSSVariables,
   type KeyboardShortcuts,
 } from './components/Piano'
 export {
   PointsEditor,
+  usePointsEditorContext,
   clampPoint,
   type PointsEditorProps,
-  type PointProps,
+  type PointsEditorContextValue,
+  type PointsEditorBackgroundProps,
+  type PointsEditorContainerProps,
+  type PointsEditorSelectionBoxProps,
+  type PointsEditorPointProps,
   type PointBaseType,
 } from './components/PointsEditor'
 export {
   Slider,
   useSliderContext,
-  type ScaleOptionProps,
-  type ScaleProps,
+  type SliderContextValue,
+  type SliderMarksOptionProps,
+  type MarksOptions,
+  type SliderMarksProps,
   type SliderMethods,
   type SliderProps,
   type SliderThumbMethods,
@@ -56,18 +64,21 @@ export {
 } from './components/Slider'
 export {
   XYPad,
+  useXYPadContext,
+  type XYPadContextValue,
   type XYPadProps,
   type XYPadMethods,
   type XYPadAreaProps,
   type XYPadThumbProps,
   type XYPadThumbMethods,
-  type ValueOptions,
+  type XY,
+  type XYInput,
 } from './components/XYPad'
 
 // hooks
 export { useAnimationFrame } from './hooks/useAnimationFrame'
 export { useDrag } from './hooks/useDrag'
-export { useDragWithElement } from './hooks/useDragWithElement'
+export { useDragValue, type UseDragValueOptions } from './hooks/useDragValue'
 export { useEventListener } from './hooks/useEventListener'
 export { useInterval } from './hooks/useInterval'
 export { useLongPress } from './hooks/useLongPress'
@@ -75,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 } from './hooks/useWheel'
+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,
+}