@tremolo-ui/react 0.8.0 → 0.9.0

package/src/components/XYPad/Thumb.tsx

@@ -1,13 +1,15 @@
 import {
   AriaAttributes,
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
+  Ref,
   useImperativeHandle,
   useRef,
-  CSSProperties,
 } from 'react'
 
-import { toXY, type XYInput } from '@tremolo-ui/dom'
+import { type XYInput } from '@tremolo-ui/dom'
+import { toXY } from '@tremolo-ui/dom/internal'
 
 import { useCheckPlacement } from '../_util/Placement'
 import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
@@ -41,6 +43,12 @@ export interface XYPadThumbProps {
   'aria-valuetext'?: XYInput<AriaAttributes['aria-valuetext']>
 
   style?: CSSProperties & CSSVariables<'color' | 'translate'>
+
+  /**
+   * Receives `focus` and `blur` for the range inputs inside, which do nothing
+   * while the pad is disabled. `ref` reaches the thumb element itself.
+   */
+  actionsRef?: Ref<XYPadThumbMethods>
 }
 
 export interface XYPadThumbMethods {
@@ -51,7 +59,7 @@ export interface XYPadThumbMethods {
 type Props = XYPadThumbProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadThumbProps>
 
-export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
+export const Thumb = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   function Thumb(
     {
       color,
@@ -62,6 +70,7 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
       'aria-labelledby': ariaLabelledby,
       'aria-describedby': ariaDescribedby,
       'aria-valuetext': ariaValuetext,
+      actionsRef,
       ...props
     },
     forwardedRef,
@@ -74,7 +83,7 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
       max,
       step,
       disabled,
-      readonly,
+      readOnly,
       onChange,
       percent,
       thumbRef,
@@ -99,15 +108,16 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
       },
     })
 
-    useImperativeHandle(forwardedRef, methods, [disabled])
+    useImperativeHandle(actionsRef, methods, [disabled])
     // Root focuses the thumb when a drag starts, wherever the user placed it.
     useImperativeHandle(thumbRef, methods, [disabled])
 
     return (
       <div
+        ref={forwardedRef}
         className={className}
         data-disabled={disabled ? '' : undefined}
-        data-readonly={readonly ? '' : undefined}
+        data-readonly={readOnly ? '' : undefined}
         {...props}
         style={{
           ...{ '--color': color },
@@ -135,14 +145,14 @@ export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
             max={max[axis]}
             step={step[axis]}
             disabled={disabled}
-            aria-readonly={readonly}
+            aria-readonly={readOnly}
             aria-orientation={axis === 0 ? 'horizontal' : 'vertical'}
             aria-label={labels[axis] ?? (axis === 0 ? 'x' : 'y')}
             aria-labelledby={labelledby[axis]}
             aria-describedby={describedby[axis]}
             aria-valuetext={valueText[axis]}
             onChange={(event) => {
-              if (readonly) {
+              if (readOnly) {
                 event.currentTarget.value = String(value[axis])
                 return
               }

package/src/components/XYPad/context.tsx

@@ -14,7 +14,7 @@ export type XYPadContextValue = {
   scale: XY<Scale>
   reverse: XY<boolean>
   disabled: boolean
-  readonly: boolean
+  readOnly: boolean
   onChange?: (value: XY<number>) => void
 
   /**

package/src/components/XYPad/index.tsx

@@ -11,25 +11,29 @@ import {
 } from 'react'
 
 import {
-  applyDelta,
-  arrowKeyMove,
   type AxisOptions,
+  type ChangeSource,
   DEFAULT_DRAG_SENSITIVITY,
   DEFAULT_KEYBOARD_OPTIONS,
   DEFAULT_WHEEL_OPTIONS,
   InputEventOption,
   ModifierState,
   type ModifierValue,
-  selectModifier,
-  toXY,
   valuePercent,
-  wheelMove,
   type XY,
   type XYInput,
 } from '@tremolo-ui/dom'
+import {
+  applyDelta,
+  arrowKeyMove,
+  selectModifier,
+  toXY,
+  wheelMove,
+} from '@tremolo-ui/dom/internal'
 import { linearScale, type Scale } from '@tremolo-ui/functions'
 
 import { useComposedRefs } from '../../compose-refs'
+import { useChangeGesture } from '../../hooks/_internal/useChangeGesture'
 import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
 import { useDragValue } from '../../hooks/useDragValue'
 import { useWheel } from '../../hooks/useWheel'
@@ -38,10 +42,6 @@ import { Area } from './Area'
 import { XYPadProvider } from './context'
 import { Thumb, XYPadThumbMethods } from './Thumb'
 
-const defaultExternalStyles: XYPadProps['externalStyles'] = {
-  cursor: 'pointer',
-}
-
 /**
  * Two-dimensional slider component.
  *
@@ -134,11 +134,9 @@ export interface XYPadProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the pad.
    *
-   * @default { cursor: 'pointer' }
+   * @default 'pointer'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor']
-  }
+  dragCursor?: CSSProperties['cursor']
 
   /**
    * Make the pad unchangeable and remove its thumb from the tab order.
@@ -149,14 +147,29 @@ export interface XYPadProps {
    * Make the pad unchangeable while leaving its thumb focusable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean
+  readOnly?: boolean
 
   /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: XY<number>) => void
-  /** Called when a drag starts, with the value where the area was pressed. */
-  onDragStart?: (value: XY<number>) => void
-  /** Called when the drag ends, with the value it ended on. */
-  onDragEnd?: (value: XY<number>) => void
+  /**
+   * Called when a change of the value starts — a press on the area, the first wheel notch
+   * or arrow key — with the value
+   * before it and what it is made with. A host recording automation can treat
+   * the control as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: XY<number>, source: ChangeSource) => void
+  /**
+   * Called when the change ends, with the value it ended on: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: XY<number>, source: ChangeSource) => void
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number
 
   /**
    * The pad renders exactly what you compose here; there is no default
@@ -170,12 +183,18 @@ export interface XYPadProps {
    * </XYPad.Root>
    */
   children: ReactNode
+
+  /**
+   * Receives `focus` and `blur`, which act on the range inputs inside the thumb —
+   * the elements that take the focus — and do nothing while
+   * the pad is disabled. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<XYPadMethods>
 }
 
 export interface XYPadMethods {
   focus: () => void
   blur: () => void
-  original: Ref<HTMLDivElement>
 }
 
 type Props = XYPadProps &
@@ -187,7 +206,7 @@ type Props = XYPadProps &
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       value,
@@ -201,17 +220,19 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
       dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       className,
       style,
-      externalStyles: _externalStyles,
+      dragCursor = 'pointer',
       disabled = false,
-      readonly = false,
+      readOnly = false,
       onChange,
-      onDragStart,
-      onDragEnd,
+      onChangeStart,
+      onChangeEnd,
+      changeEndDelay,
       onPointerDown,
       onKeyDown,
       onFocus,
       onBlur,
       children,
+      actionsRef,
       ...props
     }: Props,
     forwardedRef,
@@ -222,8 +243,20 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
     const thumbRef = useRef<XYPadThumbMethods>(null)
 
     // --- interpret props ---
-    const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
-    const inactive = disabled || readonly
+    const inactive = disabled || readOnly
+
+    const gesture = useChangeGesture(
+      value,
+      { onChangeStart, onChangeEnd, changeEndDelay },
+      inactive,
+    )
+    const change = useCallback(
+      (next: XY<number>) => {
+        gesture.changed(next)
+        onChange?.(next)
+      },
+      [gesture, onChange],
+    )
 
     const min = useMemo(() => toXY(_min), [_min])
     const max = useMemo(() => toXY(_max), [_max])
@@ -306,9 +339,10 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
         event.preventDefault()
         if (!onChange || inactive || !keyboard) return
         const { axis: i, direction } = move
-        onChange(nudge(i, reverse[i] ? -direction : direction, keyboard, event))
+        gesture.pulse('keyboard')
+        change(nudge(i, reverse[i] ? -direction : direction, keyboard, event))
       },
-      [onChange, inactive, keyboard, reverse, nudge],
+      [onChange, inactive, keyboard, reverse, nudge, gesture, change],
     )
 
     // --- hooks ---
@@ -319,21 +353,18 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
       sensitivity: (state) =>
         selectModifier(dragSensitivity, state.event).value,
       updateOnPointerDown: true,
-      cursor: inactive ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : dragCursor,
       shouldStart: () => !inactive,
       onChange: (v) => {
         if (inactive) return
-        onChange?.(v)
+        change(v)
       },
-      onDragStart: (v) => {
+      onDragStart: () => {
         if (inactive) return
+        gesture.hold('pointer')
         thumbRef.current?.focus()
-        onDragStart?.(v)
-      },
-      onDragEnd: (v) => {
-        if (inactive) return
-        onDragEnd?.(v)
       },
+      onDragEnd: () => gesture.end(),
     })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
@@ -342,12 +373,14 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
       if (!move) return
       event.preventDefault()
       const { axis: i, direction } = move
-      onChange(nudge(i, reverse[i] ? -direction : direction, wheel, event))
+      gesture.pulse('wheel')
+      change(nudge(i, reverse[i] ? -direction : direction, wheel, event))
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
     // detaching and re-attaching on every render.
     const rootRefCallback = useComposedRefs<HTMLDivElement>(
+      forwardedRef,
       rootRef,
       dragRefCallback,
       wheelRefCallback,
@@ -362,7 +395,7 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
         scale,
         reverse,
         disabled,
-        readonly,
+        readOnly,
         onChange,
         percent,
         areaRef,
@@ -376,13 +409,13 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
         scale,
         reverse,
         disabled,
-        readonly,
+        readOnly,
         onChange,
         percent,
       ],
     )
 
-    useImperativeHandle(forwardedRef, () => {
+    useImperativeHandle(actionsRef, () => {
       return {
         focus() {
           if (!disabled) thumbRef.current?.focus()
@@ -390,7 +423,6 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
         blur() {
           thumbRef.current?.blur()
         },
-        original: rootRef,
       }
     }, [disabled])
 
@@ -403,7 +435,7 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
           role="group"
           tabIndex={-1}
           data-disabled={disabled ? '' : undefined}
-          data-readonly={readonly ? '' : undefined}
+          data-readonly={readOnly ? '' : undefined}
           style={style}
           onPointerDown={onPointerDown}
           onKeyDown={(event) => {

package/src/components/_util/VisuallyHiddenRangeInput.tsx

@@ -1,6 +1,6 @@
 import { ComponentPropsWithoutRef, forwardRef } from 'react'
 
-import { visuallyHiddenStyle } from '@tremolo-ui/dom'
+import { visuallyHiddenStyle } from '@tremolo-ui/dom/internal'
 
 type Props = Omit<ComponentPropsWithoutRef<'input'>, 'type' | 'style'>
 

package/src/hooks/_internal/useChangeGesture.ts

@@ -0,0 +1,93 @@
+import {
+  useCallback,
+  useEffect,
+  useInsertionEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import {
+  createChangeGesture,
+  type ChangeGestureInstance,
+  type ChangeSource,
+} from '@tremolo-ui/dom'
+
+export interface ChangeGestureProps<V> {
+  onChangeStart?: (value: V, source: ChangeSource) => void
+  onChangeEnd?: (value: V, source: ChangeSource) => void
+  changeEndDelay?: number
+}
+
+export type ChangeGesture<V> = Pick<
+  ChangeGestureInstance,
+  'hold' | 'pulse' | 'instant' | 'end' | 'active'
+> & {
+  /**
+   * Record a value the control has just reported through `onChange`, for
+   * `onChangeEnd` to give. The prop lags behind until the parent renders, and
+   * a drag ends in the same event as its last change.
+   */
+  changed: (value: V) => void
+}
+
+/**
+ * The core's change gesture, reporting the control's value to
+ * `onChangeStart` / `onChangeEnd`. The start gets the value before the change,
+ * the end the last one reported.
+ *
+ * Internal
+ * @private
+ */
+export function useChangeGesture<V>(
+  value: V,
+  { onChangeStart, onChangeEnd, changeEndDelay }: ChangeGestureProps<V>,
+  inactive: boolean,
+): ChangeGesture<V> {
+  const [instance] = useState(() => createChangeGesture())
+  const latest = useRef({ value, onChangeStart, onChangeEnd })
+  // What `onChangeEnd` gives: the value at the start, then each one reported.
+  const lastValue = useRef(value)
+
+  useInsertionEffect(() => {
+    latest.current = { value, onChangeStart, onChangeEnd }
+  })
+
+  // The callbacks are handed over here rather than at creation: they read the
+  // refs, which belong outside render. Nothing can start a gesture before the
+  // element is mounted, so they are in place by the first event.
+  useEffect(() => {
+    instance.update({
+      endDelay: changeEndDelay,
+      onStart: (source) => {
+        lastValue.current = latest.current.value
+        latest.current.onChangeStart?.(latest.current.value, source)
+      },
+      onEnd: (source) =>
+        latest.current.onChangeEnd?.(lastValue.current, source),
+    })
+  }, [instance, changeEndDelay])
+
+  // A control that turns inactive mid-gesture, or goes away, should not leave
+  // a host thinking it is still being touched.
+  useEffect(() => {
+    if (inactive) instance.end()
+  }, [instance, inactive])
+  useEffect(() => () => instance.end(), [instance])
+
+  const changed = useCallback((next: V) => {
+    lastValue.current = next
+  }, [])
+
+  return useMemo(
+    () => ({
+      hold: instance.hold,
+      pulse: instance.pulse,
+      instant: instance.instant,
+      end: instance.end,
+      active: instance.active,
+      changed,
+    }),
+    [instance, changed],
+  )
+}

package/src/hooks/_internal/useCheckSteps.ts

@@ -1,6 +1,6 @@
 import { useEffect } from 'react'
 
-import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom'
+import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom/internal'
 
 /**
  * Warn, in development only, when a key press or a wheel notch cannot produce

package/src/hooks/useAnimationFrame.ts

@@ -1,28 +1,50 @@
-import { DependencyList, useEffect, useRef } from 'react'
+import { useEffect } from 'react'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
+export interface UseAnimationFrameOptions {
+  /**
+   * Stop the loop. Turning it back on starts a new one, whose first frame has
+   * a `deltaTime` of `0`.
+   * @default false
+   */
+  disabled?: boolean
+}
+
+/**
+ * Call `callback` on every animation frame for as long as the component is
+ * mounted.
+ *
+ * The callback is read on every frame, so it can be written inline and see
+ * the latest render without restarting the loop.
+ *
+ * @param callback receives the frame's timestamp and the milliseconds since
+ * the previous frame, which is `0` on the first one
+ */
 export function useAnimationFrame(
-  callback = () => {},
-  deps: DependencyList = [],
+  callback: (timestamp: DOMHighResTimeStamp, deltaTime: number) => void,
+  { disabled = false }: UseAnimationFrameOptions = {},
 ) {
-  const reqIdRef = useRef(-1)
   // Read through a ref rather than depended on: `useAnimationFrame(() => ...)`
   // is a new function on every render, and a callback that renders would then
-  // cancel and re-schedule its own loop on every frame. What restarts the loop
-  // is the caller's `deps`, and nothing else.
+  // cancel and re-schedule its own loop on every frame.
   const runCallback = useCallbackRef(callback)
 
   useEffect(() => {
-    // Kept inside the effect: as a `useCallback` the loop would have to
-    // reference itself before it is declared, which the compiler rules reject.
-    const loop = () => {
-      reqIdRef.current = requestAnimationFrame(loop)
-      runCallback()
+    if (disabled) return
+
+    let frameId = 0
+    let previous: DOMHighResTimeStamp | undefined
+
+    // Scheduled before calling back, so that a slow callback does not delay
+    // the next request.
+    const loop = (timestamp: DOMHighResTimeStamp) => {
+      frameId = requestAnimationFrame(loop)
+      runCallback(timestamp, previous === undefined ? 0 : timestamp - previous)
+      previous = timestamp
     }
 
-    reqIdRef.current = requestAnimationFrame(loop)
-    return () => cancelAnimationFrame(reqIdRef.current)
-    // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [runCallback, ...deps])
+    frameId = requestAnimationFrame(loop)
+    return () => cancelAnimationFrame(frameId)
+  }, [runCallback, disabled])
 }

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 = () => {}
+  }, [])
 }