@tremolo-ui/react 0.7.0 → 0.9.0

package/src/components/XYPad/index.tsx

@@ -11,33 +11,37 @@ import {
 } from 'react'
 
 import {
-  applyDelta,
   type AxisOptions,
+  type ChangeSource,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   InputEventOption,
   ModifierState,
   type ModifierValue,
-  selectModifier,
+  valuePercent,
+  type XY,
+  type XYInput,
 } from '@tremolo-ui/dom'
-import { linearScale, type Scale, toFixed } from '@tremolo-ui/functions'
+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'
-import {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from '../../input-event'
 
 import { Area } from './Area'
-import { toXY, XY, XYInput, XYPadProvider } from './context'
+import { XYPadProvider } from './context'
 import { Thumb, XYPadThumbMethods } from './Thumb'
 
-const defaultExternalStyles: XYPadProps['externalStyles'] = {
-  cursor: 'pointer',
-}
-
 /**
  * Two-dimensional slider component.
  *
@@ -130,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.
@@ -145,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
@@ -166,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 &
@@ -183,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,
@@ -197,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,
@@ -218,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])
@@ -227,14 +264,17 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
     const scale = useMemo(() => toXY(_scale), [_scale])
     const reverse = useMemo(() => toXY(_reverse), [_reverse])
 
-    const percent = useMemo((): XY<number> => {
-      const normalized = [0, 1].map((i) =>
-        scale[i].normalize(value[i], min[i], max[i]),
-      )
-      return [0, 1].map((i) =>
-        toFixed((reverse[i] ? 1 - normalized[i] : normalized[i]) * 100),
-      ) as XY<number>
-    }, [value, min, max, scale, reverse])
+    const percent = useMemo(
+      (): XY<number> =>
+        [0, 1].map((i) =>
+          valuePercent(
+            value[i],
+            { min: min[i], max: max[i], scale: scale[i] },
+            reverse[i],
+          ),
+        ) as XY<number>,
+      [value, min, max, scale, reverse],
+    )
 
     // --- internal functions ---
     // `AxisOptions` extends `ValueRange`, so the same pair also describes the
@@ -291,23 +331,18 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        const key = event.key
-        if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
-          return
-
         // The key picks the axis, whichever of the two inputs holds the
-        // focus: the pad is one control to the person moving it, and the focus
-        // lands on the x input, so reading the axis off the input would leave
-        // the y axis with no keys at all.
-        const i: 0 | 1 = key === 'ArrowRight' || key === 'ArrowLeft' ? 0 : 1
+        // focus: the focus lands on the x input, so reading the axis off the
+        // input would leave the y axis with no keys at all.
+        const move = arrowKeyMove(event.key)
+        if (!move) return
         event.preventDefault()
         if (!onChange || inactive || !keyboard) return
-        let direction = 1
-        if (key === 'ArrowLeft' || key === 'ArrowUp') direction *= -1
-        if (reverse[i]) direction *= -1
-        onChange(nudge(i, direction, keyboard, event))
+        const { axis: i, direction } = move
+        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 ---
@@ -318,43 +353,34 @@ 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) => {
       if (!onChange || inactive || !wheel) return
-      // Browsers turn shift+wheel into horizontal scrolling: `deltaY` comes
-      // out empty and `deltaX` carries the movement. Reading whichever axis
-      // moved keeps shift working as the x-axis modifier — and picks up a
-      // trackpad's own horizontal gesture, which never had a modifier.
-      const horizontal = event.deltaX !== 0
-      const delta = horizontal ? event.deltaX : event.deltaY
-      if (delta === 0) return
-      const i: 0 | 1 = horizontal || event.shiftKey ? 0 : 1
+      const move = wheelMove(event)
+      if (!move) return
       event.preventDefault()
-      let direction = 1
-      if (delta < 0) direction *= -1
-      if (reverse[i]) direction *= -1
-      onChange(nudge(i, direction, wheel, event))
+      const { axis: i, direction } = move
+      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,
@@ -369,7 +395,7 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
         scale,
         reverse,
         disabled,
-        readonly,
+        readOnly,
         onChange,
         percent,
         areaRef,
@@ -383,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()
@@ -397,7 +423,6 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
         blur() {
           thumbRef.current?.blur()
         },
-        original: rootRef,
       }
     }, [disabled])
 
@@ -410,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) => {
@@ -444,10 +469,4 @@ export const XYPad = {
 }
 
 export { type XYPadThumbProps, type XYPadThumbMethods } from './Thumb'
-export { type XYPadAreaProps } from './Area'
-export {
-  useXYPadContext,
-  type XYPadContextValue,
-  type XY,
-  type XYInput,
-} from './context'
+export { useXYPadContext, type XYPadContextValue } from './context'

package/src/components/_util/VisuallyHiddenRangeInput.tsx

@@ -1,6 +1,6 @@
 import { ComponentPropsWithoutRef, forwardRef } from 'react'
 
-import { visuallyHiddenStyle } from './visually-hidden'
+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,162 +1,25 @@
 import { useEffect } from 'react'
 
-import {
-  applyDelta,
-  type InputEventOption,
-  type ModifierState,
-  type ModifierValue,
-} from '@tremolo-ui/dom'
-import { linearScale, 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/internal'
 
 /**
  * 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.
@@ -165,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/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])
 }