@tremolo-ui/react 0.3.0 → 0.5.0

package/src/hooks/useDrag.ts

@@ -1,93 +1,58 @@
-import { useRef, useCallback } from 'react'
+import { useEffect, useState } from 'react'
 
-import { useEventListener } from './useEventListener'
-import { useRefCallbackEvent } from './useRefCallbackEvent'
+import { createDrag } from '@tremolo-ui/dom'
+
+import { useCallbackRef } from './_internal/useCallbackRef'
 
 interface UseDragProps {
+  /**
+   * Threshold at which the onDrag event fires.
+   * Prevents onDrag events from firing, for example, when double-clicking.
+   */
   threshold?: number
 
+  /** CSS cursor to show while dragging. Applied to the element itself. */
+  cursor?: string
+
   onDrag?: (x: number, y: number, deltaX: number, deltaY: number) => void
   onDragStart?: () => void
   onDragEnd?: () => void
 }
 
 /**
- * @returns [refCallback, pointerDownHandler]
+ * Track a pointer drag on an element.
+ *
+ * @returns a ref callback to attach to the element being dragged
  */
 export function useDrag<T extends Element>({
-  threshold: _threshold = 1,
+  threshold = 1,
+  cursor,
   onDrag,
   onDragStart,
   onDragEnd,
-}: UseDragProps): [
-  (div: EventTarget | null) => void,
-  (event: React.PointerEvent<T>) => void,
-] {
-  const dragOffsetX = useRef<number | undefined>(undefined)
-  const dragOffsetY = useRef<number | undefined>(undefined)
-  const dragStartX = useRef(0)
-  const dragStartY = useRef(0)
-
-  const threshold = Math.max(_threshold, 1)
-
-  const handleDrag = useCallback(
-    (
-      event: MouseEvent | React.MouseEvent<T, MouseEvent> | TouchEvent,
-      first = false,
-    ) => {
-      const isTouch = event instanceof TouchEvent
-      if (isTouch && event.cancelable) event.preventDefault()
-      const screenX = isTouch ? event.touches[0].screenX : event.screenX
-      const screenY = isTouch ? event.touches[0].screenY : event.screenY
-      let deltaX = 0
-      let deltaY = 0
-      if (first) {
-        dragStartX.current = screenX
-        dragStartY.current = screenY
-      }
-      if (dragOffsetX.current) {
-        deltaX = screenX - dragOffsetX.current
-        dragOffsetX.current = screenX
-      }
-      if (dragOffsetY.current) {
-        deltaY = screenY - dragOffsetY.current
-        dragOffsetY.current = screenY
-      }
-      if (Math.abs(deltaX) < threshold && Math.abs(deltaY) < threshold) return
-      onDrag?.(
-        screenX - dragStartX.current,
-        screenY - dragStartY.current,
-        deltaX,
-        deltaY,
-      )
-    },
-    [threshold, onDrag],
-  )
-
-  const pointerDownHandler = useCallback(
-    (event: React.PointerEvent<T>) => {
-      dragOffsetX.current = event.screenX
-      dragOffsetY.current = event.screenY
-      handleDrag(event, true)
-      onDragStart?.()
-    },
-    [handleDrag, onDragStart],
-  )
-
-  const refHandler = useRefCallbackEvent(
-    'touchmove',
-    handleDrag,
-    { passive: false },
-    [onDrag],
-  )
-
-  useEventListener(globalThis.window, 'mousemove', handleDrag)
-
-  useEventListener(globalThis.window, 'pointerup', () => {
-    dragOffsetX.current = undefined
-    dragOffsetY.current = undefined
-    onDragEnd?.()
-  })
-
-  return [refHandler, pointerDownHandler]
+}: UseDragProps): (node: T | null) => void {
+  const dragHandler = useCallbackRef(onDrag)
+  const dragStartHandler = useCallbackRef(onDragStart)
+  const dragEndHandler = useCallbackRef(onDragEnd)
+
+  // The node is held in state rather than bound in the ref callback itself, so
+  // that re-attaching the ref with the same node does not restart the drag.
+  // React re-attaches on every render when the caller passes an inline ref.
+  const [node, setNode] = useState<T | null>(null)
+
+  useEffect(() => {
+    if (!node) return
+
+    const instance = createDrag(node, {
+      threshold,
+      cursor,
+      onDragStart: () => dragStartHandler(),
+      onDrag: ({ x, y, deltaX, deltaY }) => dragHandler(x, y, deltaX, deltaY),
+      onDragEnd: () => dragEndHandler(),
+    })
+
+    return () => instance.destroy()
+  }, [node, threshold, cursor, dragHandler, dragStartHandler, dragEndHandler])
+
+  return setNode
 }

package/src/hooks/useDragValue.ts

@@ -0,0 +1,149 @@
+import { RefObject, useEffect, useRef, useState } from 'react'
+
+import {
+  createDragValue,
+  elementMapping,
+  relativeMapping,
+  type AxisOptions,
+  type DragValueInstance,
+  type XY,
+  type XYInput,
+} from '@tremolo-ui/dom'
+
+import { useCallbackRef } from './_internal/useCallbackRef'
+
+export interface UseDragValueOptions {
+  /** Scaling of each axis; a single value applies to both. */
+  axis: XYInput<AxisOptions>
+
+  /**
+   * Normalize the pointer against the bounding rect of this element, so that
+   * the value *is* the position pointed at.
+   *
+   * Give either this or `getValue`.
+   */
+  baseElementRef?: RefObject<Element | null>
+
+  /**
+   * Move the value away from where it stood when the drag started, by the
+   * distance dragged. The pointer position itself carries no meaning.
+   *
+   * Give either this or `baseElementRef`.
+   */
+  getValue?: () => XY<number>
+  /**
+   * Pixels of movement that span the whole range, with `getValue`.
+   * @default 100
+   */
+  pixelRange?: XYInput<number>
+
+  /** @see DragValueOptions.updateOnPointerDown */
+  updateOnPointerDown?: boolean
+  /** @default 0 */
+  threshold?: number
+  /** CSS cursor to show while dragging. Applied to the element itself. */
+  cursor?: string
+
+  onChange?: (value: XY<number>) => void
+  onDragStart?: (value: XY<number>) => void
+  onDragEnd?: (value: XY<number>) => void
+}
+
+/**
+ * Drive a value with a pointer drag.
+ *
+ * @returns a ref callback for the element that starts the drag, and whether a drag is in progress
+ */
+export function useDragValue<T extends Element>(
+  options: UseDragValueOptions,
+): { refCallback: (node: T | null) => void; dragging: boolean } {
+  const {
+    axis,
+    baseElementRef,
+    pixelRange,
+    updateOnPointerDown,
+    threshold,
+    cursor,
+  } = options
+
+  if (!baseElementRef && !options.getValue) {
+    throw new Error(
+      'useDragValue: give either baseElementRef or getValue, so that the drag has something to move',
+    )
+  }
+
+  const [dragging, setDragging] = useState(false)
+
+  const valueGetter = useCallbackRef(options.getValue)
+  const changeHandler = useCallbackRef(options.onChange)
+  const dragStartHandler = useCallbackRef(options.onDragStart)
+  const dragEndHandler = useCallbackRef(options.onDragEnd)
+
+  // 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(options)
+
+  const instanceRef = useRef<DragValueInstance | null>(null)
+
+  // See useDrag for why the node is held in state.
+  const [node, setNode] = useState<T | null>(null)
+
+  const [pixelRangeX, pixelRangeY] = Array.isArray(pixelRange)
+    ? pixelRange
+    : [pixelRange, pixelRange]
+
+  useEffect(() => {
+    if (!node) return
+
+    const instance = createDragValue(node, {
+      axis: latest.current.axis,
+      mapping: baseElementRef
+        ? elementMapping(() => baseElementRef.current)
+        : relativeMapping({
+            pixelRange: [pixelRangeX ?? 100, pixelRangeY ?? 100],
+          }),
+      getValue: () => valueGetter() ?? [0, 0],
+      updateOnPointerDown: latest.current.updateOnPointerDown,
+      threshold: latest.current.threshold,
+      cursor: latest.current.cursor,
+      onChange: (value) => changeHandler(value),
+      onDragStart: (value) => {
+        setDragging(true)
+        dragStartHandler(value)
+      },
+      onDragEnd: (value) => {
+        setDragging(false)
+        dragEndHandler(value)
+      },
+    })
+    instanceRef.current = instance
+
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+    }
+  }, [
+    node,
+    baseElementRef,
+    pixelRangeX,
+    pixelRangeY,
+    valueGetter,
+    changeHandler,
+    dragStartHandler,
+    dragEndHandler,
+  ])
+
+  // 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 = options
+    instanceRef.current?.update({
+      axis,
+      updateOnPointerDown,
+      threshold,
+      cursor,
+    })
+  })
+
+  return { refCallback: setNode, dragging }
+}

package/src/hooks/useEventListener.ts

@@ -1,6 +1,6 @@
 import { useEffect } from 'react'
 
-import { useCallbackRef } from './useCallbackRef'
+import { useCallbackRef } from './_internal/useCallbackRef'
 
 type Target = EventTarget | null | (() => EventTarget | null)
 type Options = boolean | AddEventListenerOptions

package/src/hooks/useWheel.ts

@@ -0,0 +1,51 @@
+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, 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)
+
+  // See useDrag for why the node is held in state.
+  const [node, setNode] = useState<T | null>(null)
+
+  useEffect(() => {
+    const element = target ? target.current : node
+    if (!element) return
+
+    const instance = createWheel(element, (event) => wheelHandler(event), {
+      requireFocus,
+    })
+
+    return () => instance.destroy()
+  }, [node, target, wheelHandler, requireFocus])
+
+  return setNode
+}

package/src/index.ts

@@ -16,49 +16,49 @@ export {
   type InitFunction,
   type RelativeSizingProps,
 } from './components/AnimationCanvas'
-export { DragObserver, type DragObserverProps } from './components/DragObserver'
 export { Knob, type KnobProps, type KnobMethods } from './components/Knob'
 export {
   NumberInput,
+  useNumberInputContext,
   type NumberInputProps,
   type NumberInputMethods,
+  type NumberInputFieldProps,
   type StepperProps,
   type IncrementStepperProps,
   type DecrementStepperProps,
 } 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 PointsEditorContextValue,
+  type PointsEditorBackgroundProps,
+  type PointsEditorContainerProps,
   type PointProps,
   type PointBaseType,
 } from './components/PointsEditor'
 export {
   Slider,
   useSliderContext,
-  type ScaleOptionProps,
-  type ScaleProps,
+  type MarksOptionProps,
+  type MarksProps,
   type SliderMethods,
   type SliderProps,
   type SliderThumbMethods,
   type SliderThumbProps,
   type SliderTrackProps,
 } from './components/Slider'
-export {
-  WheelObserver,
-  type WheelObserverProps,
-} from './components/WheelObserver'
 export {
   XYPad,
   type XYPadProps,
@@ -66,13 +66,14 @@ export {
   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'
@@ -84,3 +85,4 @@ export {
 } from './hooks/useMIDIAccess'
 export { useMIDIInput } from './hooks/useMIDIInput'
 export { useMIDIMessage } from './hooks/useMIDIMessage'
+export { useWheel, type UseWheelOptions } from './hooks/useWheel'

package/src/components/AnimationCanvas/canvas.ts

@@ -1,46 +0,0 @@
-// https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
-export const drawingState = [
-  'strokeStyle',
-  'fillStyle',
-  'globalAlpha',
-  'lineWidth',
-  'lineCap',
-  'lineJoin',
-  'miterLimit',
-  'lineDashOffset',
-  'shadowOffsetX',
-  'shadowOffsetY',
-  'shadowBlur',
-  'shadowColor',
-  'globalCompositeOperation',
-  'font',
-  'textAlign',
-  'textBaseline',
-  'direction',
-  'imageSmoothingEnabled',
-] as const
-
-export type DrawingState = (typeof drawingState)[number]
-export type DrawingStateValue = CanvasRenderingContext2D[DrawingState]
-export type DrawingContext = Pick<CanvasRenderingContext2D, DrawingState>
-
-export function isDrawingState(obj: unknown): obj is DrawingState {
-  const d: string[] = [...drawingState]
-  return typeof obj == 'string' && d.includes(obj)
-}
-
-export function setDprConfig(
-  canvas: HTMLCanvasElement,
-  context: CanvasRenderingContext2D,
-  width: number,
-  height: number,
-  dpr: number,
-) {
-  canvas.width = width * dpr
-  canvas.height = height * dpr
-  // Reset current transformation matrix to the identity matrix
-  context.setTransform(1, 0, 0, 1, 0, 0)
-  context.scale(dpr, dpr)
-  canvas.style.width = `${width}px`
-  canvas.style.height = `${height}px`
-}

package/src/components/DragObserver/index.tsx

@@ -1,58 +0,0 @@
-import { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react'
-
-import { useDrag } from '../../hooks/useDrag'
-import { Override } from '../_util/type'
-
-export interface DragObserverProps<T extends ElementType> {
-  /**
-   * React.ElementType
-   * @default div
-   */
-  as?: T
-
-  /**
-   * Threshold at which the onDrag event fires.
-   * Prevents onDrag events from firing, for example, when double-clicking.
-   */
-  threshold?: number
-
-  children?: ReactNode
-  onDrag?: (x: number, y: number, deltaX: number, deltaY: number) => void
-  onDragStart?: () => void
-  onDragEnd?: () => void
-}
-
-export function DragObserver<T extends ElementType = 'div'>(
-  props: Override<DragObserverProps<T>, ComponentPropsWithoutRef<T>>,
-) {
-  const {
-    as: Component = 'div',
-    threshold = 1,
-    onDrag,
-    onDragStart,
-    onDragEnd,
-    children,
-    onPointerDown,
-    ...attributes
-  } = props
-
-  const [refCallback, pointerDownHandler] = useDrag({
-    threshold: threshold,
-    onDrag: onDrag,
-    onDragStart: onDragStart,
-    onDragEnd: onDragEnd,
-  })
-
-  return (
-    <Component
-      ref={refCallback}
-      onPointerDown={(e) => {
-        pointerDownHandler(e)
-        onPointerDown?.(e)
-      }}
-      {...attributes}
-    >
-      {children}
-    </Component>
-  )
-}