@tremolo-ui/react 0.6.0 → 0.8.0

package/src/hooks/_internal/useCheckSteps.ts

@@ -1,163 +1,25 @@
 import { useEffect } from 'react'
 
-import {
-  applyDelta,
-  linearScale,
-  type InputEventOption,
-  type ModifierState,
-  type ModifierValue,
-  type ValueRange,
-} from '@tremolo-ui/functions'
-
-/** Positions probed across the travel. The ends are left out so that the
- * clamp at `min` and `max` cannot be mistaken for a press that does nothing. */
-const PROBES = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
-
-const NONE: ModifierState = {
-  shiftKey: false,
-  altKey: false,
-  ctrlKey: false,
-  metaKey: false,
-}
-
-const MODIFIER_STATE: Record<string, ModifierState> = {
-  shift: { ...NONE, shiftKey: true },
-  alt: { ...NONE, altKey: true },
-  ctrl: { ...NONE, ctrlKey: true },
-  meta: { ...NONE, metaKey: true },
-}
-
-/** Each entry of a modifier-aware input option, as a name and held keys. */
-function entries(
-  options: ModifierValue<InputEventOption>,
-): { name: string; modifiers: ModifierState }[] {
-  if (Array.isArray(options)) return [{ name: '', modifiers: NONE }]
-  return Object.keys(options).map((key) => ({
-    name: key === 'default' ? '' : key,
-    modifiers: MODIFIER_STATE[key] ?? NONE,
-  }))
-}
-
-interface Outcome {
-  /** The press changed the value at least once across the travel. */
-  moved: boolean
-  /** The change reached the displayed text at least once. */
-  visible: boolean
-}
-
-/**
- * Press every entry of `options` at nine points along the travel and report
- * whether anything came of it.
- *
- * Run against `applyDelta` itself rather than against a reading of `step`:
- * the whole point is that the amount, the step and the scale interact, and
- * the pipeline is the only thing that knows how.
- */
-function probe(
-  options: ModifierValue<InputEventOption>,
-  range: ValueRange,
-  format?: (value: number) => string,
-): Outcome {
-  const { min, max, scale = linearScale } = range
-  const outcome: Outcome = { moved: false, visible: false }
-
-  for (const { modifiers } of entries(options)) {
-    for (const position of PROBES) {
-      const value = scale.denormalize(position, min, max)
-      const up = applyDelta(value, 1, options, range, modifiers)
-      const down = applyDelta(value, -1, options, range, modifiers)
-      if (up !== value || down !== value) outcome.moved = true
-      if (!format) continue
-      const shown = format(value)
-      if (format(up) !== shown || format(down) !== shown) outcome.visible = true
-    }
-  }
-
-  return outcome
-}
-
-export interface CheckStepsOptions {
-  /** The component, for the message. */
-  component: string
-  /** The axis, for a component that has more than one. */
-  axis?: string
-  /**
-   * The range to probe, or `null` to check nothing. An unbounded input has no
-   * travel to sample, so `NumberInput` passes `null` when `min` and `max` are
-   * not both there.
-   */
-  range: ValueRange | null
-  keyboard?: ModifierValue<InputEventOption> | null
-  wheel?: ModifierValue<InputEventOption> | null
-  /**
-   * How the value is displayed, where the component shows one. Called with
-   * probe values only, and only in development.
-   */
-  format?: (value: number) => string
-}
+import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom'
 
 /**
  * Warn, in development only, when a key press or a wheel notch cannot produce
- * a change the user can see.
- *
- * Two settings that are each fine on their own can cancel out, and nothing
- * fails when they do — the control simply sits there:
- *
- * - **`step` coarser than the amount.** `keyboard={['raw', 0.1]}` with
- *   `step={1}` rounds every press straight back to where it started
- * - **the display coarser than the amount.** A `format` showing two decimals
- *   of a kHz value cannot show a press worth 1 Hz
- *
- * The second is only reported when the press is invisible at *every* point
- * along the travel. A display that rounds is a deliberate choice and is
- * normally right — it is being too coarse everywhere that makes it a mistake.
+ * a change the user can see. The probing is `checkSteps` in the core.
  *
  * @internal
  */
-export function useCheckSteps({
-  component,
-  axis,
-  range,
-  keyboard,
-  wheel,
-  format,
-}: CheckStepsOptions) {
+export function useCheckSteps(options: CheckStepsOptions) {
+  const { component, axis, range, keyboard, wheel } = options
   const { min, max, step, scale } = range ?? {}
-  const where = axis ? `${component} (${axis})` : component
 
   useEffect(() => {
     try {
       // Inline and first, so a bundler folds the comparison and drops the
-      // whole block — the probing and the message strings with it. See
-      // `useCheckPlacement` for why it cannot go through a helper, and why
-      // it is wrapped.
+      // whole block — and with it the only call to `checkSteps`, which then
+      // falls out of the bundle too. See `useCheckPlacement` for why it
+      // cannot go through a helper, and why it is wrapped.
       if (process.env.NODE_ENV === 'production') return
-      if (!range || min === undefined || max === undefined || !(min < max)) {
-        return
-      }
-
-      for (const [name, options] of [
-        ['keyboard', keyboard],
-        ['wheel', wheel],
-      ] as const) {
-        if (!options) continue
-        const { moved, visible } = probe(options, range, format)
-        if (!moved) {
-          console.warn(
-            `[tremolo-ui] ${where}: \`${name}\` cannot move the value.` +
-              (step !== undefined
-                ? ` Each press is smaller than \`step\` (${step}), so it rounds`
-                : ' Each press rounds') +
-              ' straight back to where it started.',
-          )
-        } else if (format && !visible) {
-          console.warn(
-            `[tremolo-ui] ${where}: \`${name}\` moves the value, but \`format\`` +
-              ' shows the same text before and after, everywhere in the range.' +
-              ' The display is too coarse for it to be seen.',
-          )
-        }
-      }
+      for (const warning of checkSteps(options)) console.warn(warning)
     } catch {
       // No bundler substituted NODE_ENV, so a production build cannot be told
       // from a development one. Say nothing rather than break.
@@ -166,5 +28,5 @@ export function useCheckSteps({
     // on what actually decides the outcome. `format` is left out on purpose:
     // an inline arrow function would make this run every render.
     // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [where, min, max, step, scale, keyboard, wheel])
+  }, [component, axis, min, max, step, scale, keyboard, wheel])
 }

package/src/hooks/useDrag.ts

@@ -4,10 +4,14 @@ import { createDrag, type DragState } from '@tremolo-ui/dom'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
-interface UseDragProps {
+export interface UseDragOptions {
   /**
-   * Threshold at which the onDrag event fires.
-   * Prevents onDrag events from firing, for example, when double-clicking.
+   * Pixels the pointer has to travel before the drag counts as one.
+   *
+   * A click moves the pointer by a pixel or two, so without a threshold a
+   * double click reports a drag between the two presses.
+   *
+   * @default 1
    */
   threshold?: number
 
@@ -24,6 +28,9 @@ interface UseDragProps {
   pointerLock?: boolean
 
   /**
+   * Called on every move once the drag has started, with the pointer position
+   * relative to the element and how far it moved since the last call.
+   *
    * @param state the whole drag, for anything the four numbers leave out —
    * the pointer event and its modifier keys, most of all.
    */
@@ -34,7 +41,9 @@ interface UseDragProps {
     deltaY: number,
     state: DragState,
   ) => void
+  /** Called once the pointer has moved past `threshold`, not on pointerdown. */
   onDragStart?: (state: DragState) => void
+  /** Called when the pointer is released, only if the drag ever started. */
   onDragEnd?: (state: DragState) => void
 }
 
@@ -50,7 +59,7 @@ export function useDrag<T extends Element>({
   onDrag,
   onDragStart,
   onDragEnd,
-}: UseDragProps): (node: T | null) => void {
+}: UseDragOptions): (node: T | null) => void {
   const dragHandler = useCallbackRef(onDrag)
   const dragStartHandler = useCallbackRef(onDragStart)
   const dragEndHandler = useCallbackRef(onDragEnd)

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/useLongPress.ts

@@ -1,65 +1,49 @@
-import { useCallback, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 
-import { useEventListener } from './useEventListener'
-import { useInterval } from './useInterval'
+import { createLongPress, type LongPressInstance } from '@tremolo-ui/dom'
 
+import { useCallbackRef } from './_internal/useCallbackRef'
+
+/**
+ * Repeat `callback` while a pointer is held down: once on the press, then
+ * every `interval` after `initialDelay`. The repeat itself is
+ * `createLongPress` in `@tremolo-ui/dom`.
+ *
+ * Returns the function that starts a press, for an `onPointerDown`.
+ */
 export function useLongPress(
   callback: () => void,
   initialDelay = 500,
   interval = 40,
 ) {
-  const [pressed, setPressed] = useState(false)
-  const [delay, setDelay] = useState(initialDelay)
-  const activePointerId = useRef<number | null>(null)
-  const isPressed = useRef(false)
-
-  useInterval(
-    () => {
-      callback()
-      setDelay(interval)
-    },
-    pressed ? delay : null,
-  )
-
-  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],
-  )
+  // Updated before layout effects run, so that a press started from one
+  // right after a re-render already calls the new callback.
+  const onPress = useCallbackRef(callback)
+  const instanceRef = useRef<LongPressInstance | null>(null)
 
-  useEventListener(globalThis.window, 'pointerup', (event) => {
-    stop(event.pointerId)
+  useEffect(() => {
+    instanceRef.current?.update({ delay: initialDelay, interval })
   })
 
-  useEventListener(globalThis.window, 'pointercancel', (event) => {
-    stop(event.pointerId)
-  })
-
-  useEventListener(globalThis.window, 'blur', () => {
-    stop()
-  })
+  useEffect(() => {
+    const instance = createLongPress({
+      onPress: () => onPress(),
+      delay: initialDelay,
+      interval,
+    })
+    instanceRef.current = instance
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+    }
+    // Created once: the options are pushed with update() above, so that a new
+    // delay does not end a press in progress.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
 
   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],
+    (event?: Pick<PointerEvent, 'button' | 'pointerId'>) =>
+      instanceRef.current?.start(event),
+    [],
   )
 }

package/src/hooks/useMIDIAccess.ts

@@ -7,14 +7,6 @@ import {
   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,

package/src/hooks/useMIDIInput.ts

@@ -2,13 +2,10 @@ import { useEffect, useRef } from 'react'
 
 import {
   createMIDIInput,
-  PITCH_BEND_CENTER,
   type MIDIInputHandlers,
   type MIDIInputInstance,
 } from '@tremolo-ui/dom'
 
-export { PITCH_BEND_CENTER, type MIDIInputHandlers }
-
 /**
  * Handle MIDI input events. To be used with {@link useMIDIAccess}.
  *

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,39 +30,26 @@ export {
   type NumberInputContextValue,
   type NumberInputProps,
   type NumberInputMethods,
-  type NumberInputInputFieldProps,
-  type NumberInputStepperProps,
-  type NumberInputIncrementStepperProps,
-  type NumberInputDecrementStepperProps,
 } from './components/NumberInput'
 export {
   Piano,
-  SHORTCUTS,
   type PianoProps,
   type PianoMethods,
   type KeyState,
   type KeyAttributes,
-  type CSSVariables,
-  type KeyboardShortcuts,
 } from './components/Piano'
 export {
   PointsEditor,
   usePointsEditorContext,
-  clampPoint,
   type PointsEditorProps,
   type PointsEditorContextValue,
-  type PointsEditorBackgroundProps,
-  type PointsEditorContainerProps,
-  type PointsEditorSelectionBoxProps,
   type PointsEditorPointProps,
-  type PointBaseType,
 } from './components/PointsEditor'
 export {
   Slider,
   useSliderContext,
   type SliderContextValue,
   type SliderMarksOptionProps,
-  type MarksOptions,
   type SliderMarksProps,
   type SliderMethods,
   type SliderProps,
@@ -68,38 +63,21 @@ export {
   type XYPadContextValue,
   type XYPadProps,
   type XYPadMethods,
-  type XYPadAreaProps,
   type XYPadThumbProps,
   type XYPadThumbMethods,
-  type XY,
-  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'
-export {
-  useMIDIAccess,
-  NOT_SUPPORTED,
-  PERMISSION_DENIED,
-  UNAVAILABLE,
-  type MIDIAccessError,
-  type MIDIAccessOptions,
-} from './hooks/useMIDIAccess'
-export {
-  useMIDIInput,
-  PITCH_BEND_CENTER,
-  type MIDIInputHandlers,
-} from './hooks/useMIDIInput'
+export { useMIDIAccess } from './hooks/useMIDIAccess'
+export { useMIDIInput } 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/components/Piano/keyboard-shortcuts.ts

@@ -1,61 +0,0 @@
-export type KeyboardShortcuts = {
-  /**
-   * Keys laid out from `noteRange.first`, one entry per semitone.
-   *
-   * An empty string leaves that note without a shortcut: `KeyboardEvent.key` is
-   * never empty, so the entry can never match. Use it to skip the black keys
-   * (see {@link SHORTCUTS.HOME_ROW_NATURAL}) and keep the remaining entries
-   * lined up with the notes.
-   */
-  keys: string[]
-}
-
-/**
- * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
- */
-export const SHORTCUTS = {
-  /** Every semitone from C, over the two rows of a QWERTY keyboard. */
-  HOME_ROW: {
-    keys: [
-      'a',
-      'w',
-      's',
-      'e',
-      'd',
-      'f',
-      't',
-      'g',
-      'y',
-      'h',
-      'u',
-      'j',
-      'k',
-      'o',
-      'l',
-      'p',
-      ';',
-    ],
-  },
-  /** The white keys only, on the home row. Black keys have no shortcut. */
-  HOME_ROW_NATURAL: {
-    keys: [
-      'a',
-      '',
-      's',
-      '',
-      'd',
-      'f',
-      '',
-      'g',
-      '',
-      'h',
-      '',
-      'j',
-      'k',
-      '',
-      'l',
-      '',
-      ';',
-    ],
-  },
-}

package/src/components/Slider/type.ts

@@ -1,44 +0,0 @@
-import { decimalPart, toFixed } from '@tremolo-ui/functions'
-
-/**
- * How `Slider.Marks` fills itself in when it is given no children: one option
- * every `per`, or every `step` of the slider. The object form turns off the
- * mark or the label for the whole set; a single option is customized by
- * writing `Slider.MarksOption` out instead.
- */
-export type MarksOptions =
-  | 'step'
-  | number
-  | {
-      per: 'step' | number
-      mark?: boolean
-      label?: boolean
-    }
-
-export function generateOptionsList(
-  options: MarksOptions,
-  min: number,
-  max: number,
-  step: number,
-) {
-  const {
-    per,
-    mark = true,
-    label = true,
-  } = typeof options === 'object' ? options : { per: options }
-  const optionsList: {
-    value: number
-    mark: boolean
-    label: boolean
-  }[] = []
-  const interval = per === 'step' ? step : per
-  const count = Math.floor(max / interval) - Math.ceil(min / interval) + 1
-  for (let i = 0; i < count; i++) {
-    const value = toFixed(
-      interval * (Math.ceil(min / interval) + i),
-      decimalPart(interval)?.length,
-    )
-    optionsList.push({ value: value, mark: mark, label: label })
-  }
-  return optionsList
-}