@tremolo-ui/react 0.7.0 → 0.9.0

package/src/hooks/useEventListener.ts

@@ -2,52 +2,123 @@ import { useCallback, useEffect, useRef } from 'react'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
-type Target = EventTarget | null | (() => EventTarget | null)
-type Options = boolean | AddEventListenerOptions
+/**
+ * What {@link useEventListener} listens on. A function is called after every
+ * render, so it can return an element out of a ref; `null` listens on nothing.
+ */
+export type UseEventListenerTarget =
+  | EventTarget
+  | null
+  | (() => EventTarget | null)
 
+/**
+ * The options of `addEventListener`, as a boolean for `capture` or as an
+ * object. `signal` is left out: the hook already owns when the listener goes.
+ */
+export type UseEventListenerOptions =
+  | boolean
+  | Pick<AddEventListenerOptions, 'capture' | 'once' | 'passive'>
+
+interface Registration {
+  node: EventTarget
+  event: string
+  capture: boolean
+  once: boolean | undefined
+  passive: boolean | undefined
+  remove: VoidFunction
+}
+
+/**
+ * Listen to an event on a target for as long as the component is mounted.
+ *
+ * The handler is read on every event, and the target and the options are
+ * compared by what they resolve to, so all three can be written inline. The
+ * listener is re-attached only when the element, the event or one of the
+ * options actually changes.
+ *
+ * @returns a function that removes the listener. It stays removed until the
+ * target, the event or the options change.
+ */
 export function useEventListener<K extends keyof DocumentEventMap>(
-  target: Target,
+  target: UseEventListenerTarget,
   event: K,
   handler: (event: DocumentEventMap[K]) => void,
-  options?: Options,
+  options?: UseEventListenerOptions,
 ): VoidFunction
 export function useEventListener<K extends keyof WindowEventMap>(
-  target: Target,
+  target: UseEventListenerTarget,
   event: K,
   handler: (event: WindowEventMap[K]) => void,
-  options?: Options,
+  options?: UseEventListenerOptions,
 ): VoidFunction
 export function useEventListener<K extends keyof GlobalEventHandlersEventMap>(
-  target: Target,
+  target: UseEventListenerTarget,
   event: K,
   handler: (event: GlobalEventHandlersEventMap[K]) => void,
-  options?: Options,
+  options?: UseEventListenerOptions,
 ): VoidFunction
 export function useEventListener(
-  target: Target,
+  target: UseEventListenerTarget,
   event: string,
   handler: (event: Event) => void,
-  options?: Options,
+  options?: UseEventListenerOptions,
 ) {
   const listener = useCallbackRef(handler)
-  const cleanupRef = useRef<VoidFunction>(() => {})
+  const registrationRef = useRef<Registration | null>(null)
+
+  const {
+    capture = false,
+    once,
+    passive,
+  } = typeof options === 'boolean' ? { capture: options } : (options ?? {})
 
+  // No dependency list: an inline target or options object is a new value on
+  // every render, so what decides a re-attach is the comparison below, not
+  // their identity.
   useEffect(() => {
-    const node = typeof target === 'function' ? target() : (target ?? document)
+    const node = typeof target === 'function' ? target() : target
+    const current = registrationRef.current
 
+    if (
+      current &&
+      current.node === node &&
+      current.event === event &&
+      current.capture === capture &&
+      current.once === once &&
+      current.passive === passive
+    ) {
+      return
+    }
+
+    current?.remove()
+    registrationRef.current = null
     if (!node) return
 
-    node.addEventListener(event, listener, options)
-    const cleanup = () => {
-      node.removeEventListener(event, listener, options)
+    const listenerOptions = { capture, once, passive }
+    node.addEventListener(event, listener, listenerOptions)
+    registrationRef.current = {
+      node,
+      event,
+      capture,
+      once,
+      passive,
+      remove: () => node.removeEventListener(event, listener, listenerOptions),
     }
-    cleanupRef.current = cleanup
+  })
 
-    return () => {
-      cleanup()
-      if (cleanupRef.current === cleanup) cleanupRef.current = () => {}
-    }
-  }, [event, target, options, listener])
+  useEffect(
+    () => () => {
+      registrationRef.current?.remove()
+      registrationRef.current = null
+    },
+    [],
+  )
 
-  return useCallback(() => cleanupRef.current(), [])
+  // Kept registered, so a render with the same target does not attach again.
+  return useCallback(() => {
+    const current = registrationRef.current
+    if (!current) return
+    current.remove()
+    current.remove = () => {}
+  }, [])
 }

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,9 +4,8 @@ import { createWheel, type WheelOptions } from '@tremolo-ui/dom'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
-// `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.
+// `onWheel` is left out: this hook takes the handler as its first argument, so
+// the option would be a second way to say the same thing.
 export interface UseWheelOptions extends Omit<WheelOptions, 'onWheel'> {
   /**
    * Listen on this element rather than on the one the returned ref callback is
@@ -43,7 +42,8 @@ export function useWheel<T extends Element>(
     const element = target ? target.current : node
     if (!element) return
 
-    const instance = createWheel(element, (event) => wheelHandler(event), {
+    const instance = createWheel(element, {
+      onWheel: (event) => wheelHandler(event),
       requireFocus,
     })
 

package/src/index.ts

@@ -4,8 +4,6 @@ export {
   type AnimationCanvasFixedProps,
   type AnimationCanvasProps,
   type AnimationCanvasResizableProps,
-  type DrawFunction,
-  type InitFunction,
 } from './components/AnimationCanvas'
 export { DropZone, type DropZoneProps } from './components/DropZone'
 export {
@@ -33,28 +31,23 @@ export {
 } from './components/NumberInput'
 export {
   Piano,
-  SHORTCUTS,
   type PianoProps,
   type PianoMethods,
   type KeyState,
   type KeyAttributes,
-  type KeyboardShortcuts,
 } from './components/Piano'
 export {
   PointsEditor,
   usePointsEditorContext,
-  clampPoint,
   type PointsEditorProps,
   type PointsEditorContextValue,
   type PointsEditorPointProps,
-  type PointBaseType,
 } from './components/PointsEditor'
 export {
   Slider,
   useSliderContext,
   type SliderContextValue,
   type SliderMarksOptionProps,
-  type MarksOptions,
   type SliderMarksProps,
   type SliderMethods,
   type SliderProps,
@@ -68,41 +61,27 @@ 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 {
+  useAnimationFrame,
+  type UseAnimationFrameOptions,
+} from './hooks/useAnimationFrame'
 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'
+  useEventListener,
+  type UseEventListenerOptions,
+  type UseEventListenerTarget,
+} from './hooks/useEventListener'
+export { useLongPress } from './hooks/useLongPress'
+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,46 +0,0 @@
-import { toFixed } from '@tremolo-ui/functions'
-
-import { decimalDigits } from '../_util/decimal-digits'
-
-/**
- * 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),
-      decimalDigits(interval),
-    )
-    optionsList.push({ value: value, mark: mark, label: label })
-  }
-  return optionsList
-}

package/src/components/_util/css-length.ts

@@ -1,13 +0,0 @@
-/**
- * A number as a CSS length, for a custom property.
- *
- * React appends `px` to a bare number for the properties it knows take a
- * length, and a custom property is never one of them: `--size: 50` would come
- * out as the invalid `50`. Anything already a string is passed through, so
- * `'3rem'` and `'100%'` still work.
- */
-export function cssLength(
-  value: number | string | undefined,
-): string | undefined {
-  return typeof value === 'number' ? `${value}px` : value
-}

package/src/components/_util/decimal-digits.ts

@@ -1,23 +0,0 @@
-/**
- * How many digits a number carries after the decimal point.
- *
- * `Slider.Marks` builds its labels by multiplying an interval, which leaves
- * binary debris in the last digits (`0.1 * 3` is `0.30000000000000004`). The
- * count is what tells `toFixed` how far to round that back.
- *
- * The exponent form has to be handled separately: `String(1e-7)` is `'1e-7'`,
- * which has no decimal point at all, so reading the text after the point
- * reports no digits and the interval rounds away to whole numbers.
- */
-export function decimalDigits(x: number): number {
-  if (!Number.isFinite(x)) return 0
-
-  const text = String(x)
-  const e = text.indexOf('e')
-  if (e === -1) return text.split('.')[1]?.length ?? 0
-
-  const fraction = text.slice(0, e).split('.')[1]?.length ?? 0
-  // A negative exponent pushes the point further right, a positive one pulls
-  // it back past the digits that are there.
-  return Math.max(0, fraction - Number(text.slice(e + 1)))
-}

package/src/components/_util/visually-hidden.ts

@@ -1,25 +0,0 @@
-import type { CSSProperties } from 'react'
-
-/**
- * Take an element out of sight while leaving it in the accessibility tree and
- * in the tab order.
- *
- * `display: none` and `visibility: hidden` would remove it from both, and the
- * native control underneath a headless component is what carries the ARIA and
- * the keyboard behaviour. `pointer-events: none` is safe because nothing is
- * ever clicked here directly: a `<label>` forwards its click, and a drag is
- * handled by the part that is visible.
- */
-export const visuallyHiddenStyle: CSSProperties = {
-  position: 'absolute',
-  width: 1,
-  height: 1,
-  padding: 0,
-  margin: -1,
-  overflow: 'hidden',
-  clip: 'rect(0, 0, 0, 0)',
-  clipPath: 'inset(50%)',
-  whiteSpace: 'nowrap',
-  border: 0,
-  pointerEvents: 'none',
-}

package/src/hooks/useInterval.ts

@@ -1,27 +0,0 @@
-import { useEffect, useRef } from 'react'
-
-export function useInterval(callback: () => void, delay: number | null) {
-  const savedCallback = useRef(callback)
-
-  // Remember the latest callback if it changes.
-  useEffect(() => {
-    savedCallback.current = callback
-  }, [callback])
-
-  // Set up the interval.
-  useEffect(() => {
-    // Don't schedule if no delay is specified.
-    // Note: 0 is a valid value for delay.
-    if (delay === null) {
-      return
-    }
-
-    const id = setInterval(() => {
-      savedCallback.current()
-    }, delay)
-
-    return () => {
-      clearInterval(id)
-    }
-  }, [delay])
-}

package/src/input-event.ts

@@ -1,32 +0,0 @@
-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,
-}