@tremolo-ui/react 0.5.0 → 0.7.0

package/src/hooks/useDropZone.ts

@@ -0,0 +1,78 @@
+import { useEffect, useRef, useState } from 'react'
+
+import {
+  createDropZone,
+  type DropZoneInstance,
+  type DropZoneOptions,
+} from '@tremolo-ui/dom'
+
+import { useCallbackRef } from './_internal/useCallbackRef'
+
+// `onStateChange` is left out: what it reports comes back from the hook as
+// `over` and `invalid`, which is what a component renders from.
+export interface UseDropZoneOptions extends Omit<
+  DropZoneOptions,
+  'onStateChange'
+> {}
+
+/**
+ * Take files dropped onto an element.
+ *
+ * Any element can become a drop target this way — a waveform display, a track
+ * lane, a canvas — without wrapping it in anything.
+ *
+ * @returns a ref callback for the element, and whether a drag is over it
+ */
+export function useDropZone<T extends Element>({
+  accept,
+  multiple,
+  disabled,
+  onDrop,
+  onReject,
+}: UseDropZoneOptions = {}): {
+  refCallback: (node: T | null) => void
+  over: boolean
+  invalid: boolean
+} {
+  const dropHandler = useCallbackRef(onDrop)
+  const rejectHandler = useCallbackRef(onReject)
+
+  const [state, setState] = useState({ over: false, invalid: false })
+
+  // See useDrag for why the node is held in state.
+  const [node, setNode] = useState<T | null>(null)
+
+  const instanceRef = useRef<DropZoneInstance | null>(null)
+
+  // Read when the instance is created. The effect below keeps it current, and
+  // runs right after, so a stale setting is replaced within the same commit.
+  const latest = useRef({ accept, multiple, disabled })
+
+  useEffect(() => {
+    if (!node) return
+
+    const instance = createDropZone(node, {
+      ...latest.current,
+      onDrop: (files, event) => dropHandler(files, event),
+      onReject: (files, event) => rejectHandler(files, event),
+      onStateChange: (next) => setState(next),
+    })
+    instanceRef.current = instance
+
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+      // The listeners are gone, so no `dragleave` is coming to clear this.
+      setState({ over: false, invalid: false })
+    }
+  }, [node, dropHandler, rejectHandler])
+
+  // Runs after every render: the settings come from props and are cheap to
+  // push, and updating in place leaves a drag in progress untouched.
+  useEffect(() => {
+    latest.current = { accept, multiple, disabled }
+    instanceRef.current?.update({ accept, multiple, disabled })
+  })
+
+  return { refCallback: setNode, over: state.over, invalid: state.invalid }
+}

package/src/hooks/useEventListener.ts

@@ -1,4 +1,4 @@
-import { useEffect } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
@@ -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

@@ -4,7 +4,10 @@ import { createWheel, type WheelOptions } from '@tremolo-ui/dom'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
-export interface UseWheelOptions extends WheelOptions {
+// `onWheel` is left out: `createWheel` takes it so that `update()` can replace
+// the callback, but this hook takes the handler as its first argument and the
+// option would be silently ignored.
+export interface UseWheelOptions extends Omit<WheelOptions, 'onWheel'> {
   /**
    * Listen on this element rather than on the one the returned ref callback is
    * attached to, and ignore that callback.

package/src/index.ts

@@ -1,31 +1,35 @@
-// 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 { DropZone, type DropZoneProps } from './components/DropZone'
+export {
+  FileInput,
+  useFileInputContext,
+  type FileInputContextValue,
+  type FileInputProps,
+  type FileInputTriggerProps,
+} from './components/FileInput'
+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,
 } from './components/NumberInput'
 export {
   Piano,
@@ -34,7 +38,6 @@ export {
   type PianoMethods,
   type KeyState,
   type KeyAttributes,
-  type CSSVariables,
   type KeyboardShortcuts,
 } from './components/Piano'
 export {
@@ -43,16 +46,16 @@ export {
   clampPoint,
   type PointsEditorProps,
   type PointsEditorContextValue,
-  type PointsEditorBackgroundProps,
-  type PointsEditorContainerProps,
-  type PointProps,
+  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,
@@ -70,10 +75,13 @@ export {
   type XYInput,
 } from './components/XYPad'
 
+export { type CSSVariables } from './css-variables'
+
 // hooks
 export { useAnimationFrame } from './hooks/useAnimationFrame'
-export { useDrag } from './hooks/useDrag'
+export { useDrag, type UseDragOptions } from './hooks/useDrag'
 export { useDragValue, type UseDragValueOptions } from './hooks/useDragValue'
+export { useDropZone, type UseDropZoneOptions } from './hooks/useDropZone'
 export { useEventListener } from './hooks/useEventListener'
 export { useInterval } from './hooks/useInterval'
 export { useLongPress } from './hooks/useLongPress'
@@ -81,8 +89,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, type ModifierValue } from '@tremolo-ui/dom'
+
+/**
+ * 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/dom`.
+ */
+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,
+}