@tremolo-ui/react 0.4.0 → 0.5.0

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

@@ -1,18 +1,35 @@
-import { useEffect, useState } from 'react'
-
-import { createWheel } from '@tremolo-ui/dom'
-
-import { useCallbackRef } from './useCallbackRef'
+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
+ * @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)
 
@@ -20,12 +37,15 @@ export function useWheel<T extends Element>(
   const [node, setNode] = useState<T | null>(null)
 
   useEffect(() => {
-    if (!node) return
+    const element = target ? target.current : node
+    if (!element) return
 
-    const instance = createWheel(node, (event) => wheelHandler(event))
+    const instance = createWheel(element, (event) => wheelHandler(event), {
+      requireFocus,
+    })
 
     return () => instance.destroy()
-  }, [node, wheelHandler])
+  }, [node, target, wheelHandler, requireFocus])
 
   return setNode
 }

package/src/index.ts

@@ -19,35 +19,40 @@ export {
 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,
@@ -61,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'
@@ -79,4 +85,4 @@ export {
 } from './hooks/useMIDIAccess'
 export { useMIDIInput } from './hooks/useMIDIInput'
 export { useMIDIMessage } from './hooks/useMIDIMessage'
-export { useWheel } from './hooks/useWheel'
+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/NumberInput/InternalInput.tsx

@@ -1,216 +0,0 @@
-import clsx from 'clsx'
-import {
-  ComponentPropsWithoutRef,
-  forwardRef,
-  useCallback,
-  useImperativeHandle,
-  useMemo,
-  useRef,
-  useState,
-} from 'react'
-
-import {
-  clamp,
-  InputEventOption,
-  normalizeValue,
-  rawValue,
-  stepValue,
-} from '@tremolo-ui/functions'
-
-import { useWheel } from '../../hooks/useWheel'
-
-import { safeClamp, useNumberInputContext } from './context'
-import { parseValue } from './type'
-
-import { NumberInputMethods } from '.'
-
-interface InternalProps {
-  disabled: boolean
-  readonly: boolean
-  wheel: InputEventOption | null
-  keyboard: InputEventOption | null
-
-  selectWithFocus?: 'all' | 'number' | 'none'
-  blurOnEnter?: boolean
-  keepWithinRange?: boolean
-  clampValueOnBlur?: boolean
-
-  onChange?: (value: number, text: string) => void
-  onFocus?: (
-    value: number,
-    text: string,
-    event: React.FocusEvent<HTMLInputElement, Element>,
-  ) => void
-  onBlur?: (
-    value: number,
-    text: string,
-    event: React.FocusEvent<HTMLInputElement, Element>,
-  ) => void
-}
-
-type InternalPropsWithAttributes = InternalProps &
-  Omit<ComponentPropsWithoutRef<'input'>, keyof InternalProps>
-
-export const InternalInput = forwardRef<
-  NumberInputMethods,
-  InternalPropsWithAttributes
->(
-  (
-    {
-      disabled,
-      readonly,
-      selectWithFocus,
-      blurOnEnter,
-      clampValueOnBlur,
-      wheel,
-      keyboard,
-      className,
-      onChange,
-      onFocus,
-      onBlur,
-      onKeyDown,
-      children: _children,
-      ...props
-    }: InternalPropsWithAttributes,
-    ref,
-  ) => {
-    const elmRef = useRef<HTMLInputElement>(null)
-    const [editing, setEditing] = useState(false)
-    const value = useNumberInputContext((s) => s.value)
-    const valueAsNumber = useNumberInputContext((s) => s.valueAsNumber)
-    const min = useNumberInputContext((s) => s.min)
-    const max = useNumberInputContext((s) => s.max)
-    const step = useNumberInputContext((s) => s.step)
-    const units = useNumberInputContext((s) => s.units)
-    const digit = useNumberInputContext((s) => s.digit)
-    const change = useNumberInputContext((s) => s.change)
-
-    const error = useMemo(() => {
-      if (editing) return false
-      const v = valueAsNumber
-      return (min ?? -Infinity) > v || v > (max ?? Infinity)
-    }, [editing, max, min, valueAsNumber])
-
-    const updateValueByEvent = useCallback(
-      (eventType: InputEventOption[0], x: number) => {
-        let newValue
-        if (eventType == 'normalized') {
-          if (!min || !max) {
-            throw new Error(
-              '[NumberInput] "min" and "max" are required when InputEventOption[0] is set to "normalized".',
-            )
-          }
-          const n = normalizeValue(valueAsNumber, min, max)
-          newValue = rawValue(n + x, min, max)
-          return clamp(stepValue(newValue, step), min, max)
-        } else {
-          newValue = valueAsNumber + x
-          return stepValue(newValue, step)
-        }
-      },
-      [max, min, step, valueAsNumber],
-    )
-
-    const handleKeyDown = useCallback(
-      (event: React.KeyboardEvent<HTMLDivElement>) => {
-        if (!keyboard || !onChange || readonly) return
-        const key = event.key
-        if (!['ArrowUp', 'ArrowDown'].includes(key)) return
-        event.preventDefault()
-        const x = key == 'ArrowUp' ? keyboard[1] : -keyboard[1]
-        const parsed = parseValue(String(updateValueByEvent(keyboard[0], x)))
-        // console.log('key control')
-        onChange?.(parsed.rawValue, parsed.formatValue)
-      },
-      [keyboard, readonly, onChange, updateValueByEvent],
-    )
-
-    const wheelRefCallback = useWheel<HTMLInputElement>((event) => {
-      if (!wheel || readonly) return
-      event.preventDefault()
-      if (!onChange || event.deltaY == 0) return
-      const x = Math.sign(event.deltaY) * -wheel[1]
-      const parsed = parseValue(String(updateValueByEvent(wheel[0], x)))
-      // console.log('wheel control')
-      onChange?.(parsed.rawValue, parsed.formatValue)
-    })
-
-    useImperativeHandle(ref, () => {
-      return {
-        focus() {
-          elmRef.current?.focus()
-        },
-        blur() {
-          elmRef.current?.blur()
-        },
-      }
-    }, [])
-
-    return (
-      <input
-        ref={(input) => {
-          elmRef.current = input
-          wheelRefCallback(input)
-        }}
-        className={clsx('tremolo-number-input', className)}
-        value={value}
-        min={min}
-        max={max}
-        step={step}
-        type="text"
-        aria-disabled={disabled}
-        aria-readonly={readonly}
-        tabIndex={-1}
-        data-error={error}
-        onChange={(event) => {
-          if (readonly) return
-          const v = event.currentTarget.value
-          const cursorPos = event.target.selectionStart
-          change(v)
-          const valueAsNumber = parseValue(v, units, digit).rawValue
-          onChange?.(valueAsNumber, v)
-          if (cursorPos) {
-            event.target.selectionStart = cursorPos
-            event.target.selectionEnd = cursorPos
-          }
-        }}
-        onFocus={(event) => {
-          setEditing(true)
-          const v = event.currentTarget.value
-          const parsed = parseValue(v, units, digit)
-          if (selectWithFocus == 'all') {
-            event.currentTarget.setSelectionRange(0, v.length)
-          } else if (selectWithFocus == 'number') {
-            event.currentTarget.setSelectionRange(
-              0,
-              parsed.formatValue.length - parsed.unit.length,
-            )
-          }
-          onFocus?.(parsed.rawValue, parsed.formatValue, event)
-        }}
-        onBlur={(event) => {
-          setEditing(false)
-          // update value
-          let v = parseValue(event.currentTarget.value, units, digit).rawValue
-          if (clampValueOnBlur) {
-            v = safeClamp(v, min, max)
-          }
-          const parsed = parseValue(String(v), units, digit)
-          change(parsed.formatValue)
-          if (clampValueOnBlur) {
-            onChange?.(parsed.rawValue, parsed.formatValue)
-          }
-          onBlur?.(parsed.rawValue, parsed.formatValue, event)
-        }}
-        onKeyDown={(event) => {
-          if (blurOnEnter && event.key == 'Enter') {
-            event.currentTarget.blur()
-          }
-          handleKeyDown(event)
-          onKeyDown?.(event)
-        }}
-        {...props}
-      />
-    )
-  },
-)

package/src/components/NumberInput/type.ts

@@ -1,58 +0,0 @@
-/**
- * [unit, scale][]
- * @example
- * [['Hz', 1], ['kHz', 1000]]
- */
-export type Units = [string, number][]
-
-export function selectUnit(units: Units, value: number): [string, number] {
-  let i = 0
-  for (; i < units.length; i++) {
-    if (Math.abs(units[i][1]) > Math.abs(value)) break
-  }
-  return units[Math.max(0, i - 1)]
-}
-
-export function parseValue(
-  inputString: string,
-  units?: string | Units,
-  digit?: number,
-): {
-  rawValue: number
-  formatValue: string
-  unit: string
-} {
-  const str = inputString.trim()
-  if (!units || typeof units == 'string') {
-    const m = str.match(/-?\d+(\.\d+)?/)
-    let v = Number(m?.[0] ?? '0')
-    v = isNaN(v) ? 0 : v
-    return {
-      rawValue: v,
-      formatValue: (digit != undefined ? v.toFixed(digit) : v) + (units ?? ''),
-      unit: units ?? '',
-    }
-  }
-
-  const unitList = units.map(([u, _s]) => u)
-  const scaleList = units.map(([_u, s]) => s)
-  let rawValue = 0
-  let unit = unitList[0]
-  let formatValue =
-    (digit != undefined ? rawValue.toFixed(digit) : rawValue) + unit
-  const m = str.match(/^(-?\d+(\.\d+)?)\s*(\w*)$/)
-  if (m) {
-    rawValue = Number(m[1]) || 0
-    const uIndex = unitList.indexOf(m[3])
-    rawValue *= uIndex != -1 ? scaleList[uIndex] : 1
-    const [u, scale] = selectUnit(units, rawValue)
-    const v = rawValue / scale
-    formatValue = (digit != undefined ? v.toFixed(digit) : v) + u
-    unit = u
-  }
-  return {
-    rawValue: rawValue,
-    formatValue: formatValue,
-    unit: unit,
-  }
-}

package/src/components/Piano/KeyLabel.tsx

@@ -1,51 +0,0 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, CSSProperties, ReactNode } from 'react'
-
-import { usePianoContext } from './context'
-
-import { getNoteRangeArray } from '.'
-
-export interface KeyLabelProps {
-  /**
-   * override Piano.label
-   */
-  label?: (note: number, index: number) => ReactNode
-
-  wrapperClassName?: string
-  wrapperStyle?: CSSProperties
-
-  /** @internal */
-  __note?: number
-  /** @internal */
-  __label?: (note: number, index: number) => ReactNode
-}
-
-export function KeyLabel({
-  label,
-  className,
-  wrapperClassName,
-  wrapperStyle,
-  __note,
-  __label,
-  ...props
-}: KeyLabelProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KeyLabelProps>) {
-  const noteRange = usePianoContext((s) => s.noteRange)
-  const noteRangeArray = getNoteRangeArray(noteRange)
-  const index = noteRangeArray.indexOf(__note!)
-  const content = label
-    ? label(__note!, index)
-    : __label && __label(__note!, index)
-
-  return (
-    (content != undefined || content != null) && (
-      <div
-        className={clsx('tremolo-piano-key-label-wrapper', wrapperClassName)}
-        style={wrapperStyle}
-      >
-        <div className={clsx('tremolo-piano-key-label', className)} {...props}>
-          {content}
-        </div>
-      </div>
-    )
-  )
-}