@tremolo-ui/react 0.6.0 → 0.7.0

package/src/hooks/useDragValue.ts

@@ -51,9 +51,19 @@ export interface UseDragValueOptions {
    */
   sensitivity?: (state: DragState) => number
 
-  /** @see DragValueOptions.updateOnPointerDown */
+  /**
+   * Move the value on pointerdown, before the pointer has moved at all. With
+   * `baseElementRef` that makes a press jump the value to where it landed.
+   *
+   * @see DragValueOptions.updateOnPointerDown
+   */
   updateOnPointerDown?: boolean
-  /** @default 0 */
+  /**
+   * Pixels the pointer has to travel before the drag counts as one. The
+   * default is 0, so the value follows the very first move.
+   *
+   * @default 0
+   */
   threshold?: number
   /** CSS cursor to show while dragging. Applied to the element itself. */
   cursor?: string
@@ -75,11 +85,16 @@ export interface UseDragValueOptions {
   shouldStart?: (event: PointerEvent) => boolean
 
   /**
+   * Called with the new value whenever the drag moves it. The hook holds no
+   * value of its own, so this is where it is stored.
+   *
    * @param state the whole drag, for anything the value leaves out — the
    * pointer event and its modifier keys, most of all.
    */
   onChange?: (value: XY<number>, state: DragState) => void
+  /** Called once the drag starts, with the value it starts from. */
   onDragStart?: (value: XY<number>, state: DragState) => void
+  /** Called when the pointer is released, with the value it ends on. */
   onDragEnd?: (value: XY<number>, state: DragState) => void
 }
 

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/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

@@ -7,6 +7,14 @@ export {
   type DrawFunction,
   type InitFunction,
 } from './components/AnimationCanvas'
+export { DropZone, type DropZoneProps } from './components/DropZone'
+export {
+  FileInput,
+  useFileInputContext,
+  type FileInputContextValue,
+  type FileInputProps,
+  type FileInputTriggerProps,
+} from './components/FileInput'
 export {
   Knob,
   useKnobContext,
@@ -22,10 +30,6 @@ export {
   type NumberInputContextValue,
   type NumberInputProps,
   type NumberInputMethods,
-  type NumberInputInputFieldProps,
-  type NumberInputStepperProps,
-  type NumberInputIncrementStepperProps,
-  type NumberInputDecrementStepperProps,
 } 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,9 +46,6 @@ export {
   clampPoint,
   type PointsEditorProps,
   type PointsEditorContextValue,
-  type PointsEditorBackgroundProps,
-  type PointsEditorContainerProps,
-  type PointsEditorSelectionBoxProps,
   type PointsEditorPointProps,
   type PointBaseType,
 } from './components/PointsEditor'
@@ -75,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'

package/src/input-event.ts

@@ -1,4 +1,4 @@
-import type { InputEventOption, ModifierValue } from '@tremolo-ui/functions'
+import { type InputEventOption, type ModifierValue } from '@tremolo-ui/dom'
 
 /**
  * The keyboard amount used by Knob, NumberInput, Slider, and XYPad by default:
@@ -7,7 +7,7 @@ import type { InputEventOption, ModifierValue } from '@tremolo-ui/functions'
  * `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`.
+ * amount move at all — see `applyDelta` in `@tremolo-ui/dom`.
  */
 export const DEFAULT_KEYBOARD_OPTIONS: ModifierValue<InputEventOption> = {
   default: ['raw', 1],