@tremolo-ui/react 0.8.0 → 0.9.0

package/src/components/NumberInput/context.tsx

@@ -1,4 +1,4 @@
-import { createContext, RefObject, useContext } from 'react'
+import { createContext, CSSProperties, RefObject, useContext } from 'react'
 
 import {
   type InputEventOption,
@@ -22,7 +22,7 @@ export type NumberInputContextValue = {
   scale: Scale
 
   disabled: boolean
-  readonly: boolean
+  readOnly: boolean
   clampValue: boolean
 
   /**
@@ -40,6 +40,8 @@ export type NumberInputContextValue = {
   dragSensitivity: ModifierValue<number>
   /** Whether a `Stepper` drag hides the pointer and reads its movement. */
   pointerLock: boolean
+  /** The cursor shown while a `Stepper` is dragged. */
+  dragCursor: CSSProperties['cursor']
 
   /** What `InputField` selects when it takes focus. */
   selectOnFocus: 'all' | 'number' | 'none'
@@ -101,6 +103,26 @@ export function useNumberInputContext<T>(
   return selector ? selector(context) : context
 }
 
+/**
+ * The change gesture of `Root`, for the parts that change the value. Not on
+ * the public context: it is how the parts report, not something to read.
+ */
+export type NumberInputGestureValue = {
+  /** A press on a stepper, held until the pointer is released anywhere. */
+  press: () => void
+  /** An arrow key in `InputField`. */
+  key: () => void
+}
+
+const NumberInputGestureContext =
+  /* @__PURE__ */ createContext<NumberInputGestureValue | null>(null)
+
+export const NumberInputGestureProvider = NumberInputGestureContext.Provider
+
+export function useNumberInputGesture(): NumberInputGestureValue | null {
+  return useContext(NumberInputGestureContext)
+}
+
 /** Set by `Stepper` once a drag has actually moved, so the steppers stand down. */
 export type StepperContextValue = {
   /** Whether the drag in progress has moved the value. */

package/src/components/NumberInput/index.tsx

@@ -1,7 +1,9 @@
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
   ReactNode,
+  Ref,
   useCallback,
   useImperativeHandle,
   useMemo,
@@ -10,25 +12,30 @@ import {
 } from 'react'
 
 import {
+  type ChangeSource,
   DEFAULT_DRAG_SENSITIVITY,
   DEFAULT_KEYBOARD_OPTIONS,
   DEFAULT_WHEEL_OPTIONS,
-  commitNumberInputText,
   InputEventOption,
   ModifierState,
   type ModifierValue,
+} from '@tremolo-ui/dom'
+import {
+  commitNumberInputText,
   numberInputBounds,
   numberInputRanges,
   nudgeNumberInput,
   parseNumberText,
   wheelDirection,
-} from '@tremolo-ui/dom'
+} 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 { useWheel } from '../../hooks/useWheel'
 
-import { NumberInputProvider } from './context'
+import { NumberInputGestureProvider, NumberInputProvider } from './context'
 import { DecrementStepper } from './DecrementStepper'
 import { IncrementStepper } from './IncrementStepper'
 import { InputField } from './InputField'
@@ -162,6 +169,13 @@ export interface NumberInputProps {
    * @default false
    */
   pointerLock?: boolean
+  /**
+   * The cursor to show while dragging a `Stepper`. It is set on the stepper
+   * being dragged, so it stays while the pointer is outside it.
+   *
+   * @default 'ns-resize'
+   */
+  dragCursor?: CSSProperties['cursor']
 
   /**
    * Select the text when `InputField` takes focus: `'all'` selects all of it,
@@ -219,7 +233,7 @@ export interface NumberInputProps {
    * Make the value unchangeable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean
+  readOnly?: boolean
 
   /**
    * Called with the new value. While the user types, it is called for every
@@ -227,6 +241,27 @@ export interface NumberInputProps {
    * again if clamping changes the value.
    */
   onChange?: (value: number) => void
+  /**
+   * Called when a change of the value starts — a press on a stepper, the
+   * first wheel notch, arrow key or typed character — with the value before
+   * it and what it is made with. A host recording automation can treat the
+   * input as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: number, source: ChangeSource) => void
+  /**
+   * Called when the change ends, with the value it ended on: when the stepper
+   * is released, when typed text is committed, or `changeEndDelay` after the
+   * last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: number, source: ChangeSource) => void
+  /**
+   * How long after the last wheel notch, arrow key or typed character the
+   * change counts as over, in milliseconds. None of them has an event that
+   * says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number
 
   /**
    * The input renders exactly what you compose here; there is no default
@@ -242,6 +277,13 @@ export interface NumberInputProps {
    * </NumberInput.Root>
    */
   children: ReactNode
+
+  /**
+   * Receives `focus` and `blur`, which act on the input of `InputField` — the
+   * element that takes the focus — and do nothing while
+   * the input is disabled. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<NumberInputMethods>
 }
 
 export interface NumberInputMethods {
@@ -254,7 +296,7 @@ const defaultFormat = (value: number) => String(value)
 type Props = NumberInputProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof NumberInputProps>
 
-export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       value,
@@ -270,16 +312,21 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
       drag = 1,
       dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       pointerLock = false,
+      dragCursor = 'ns-resize',
       selectOnFocus = 'none',
       unformatOnFocus = false,
       keepCaretOnStep = false,
       blurOnEnter = true,
       disabled = false,
-      readonly = false,
+      readOnly = false,
       className,
       style,
       onChange,
+      onChangeStart,
+      onChangeEnd,
+      changeEndDelay,
       children,
+      actionsRef,
       ...props
     }: Props,
     forwardedRef,
@@ -291,7 +338,13 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
      * but the half-finished entry that has no value to be derived from yet.
      */
     const [draft, setDraft] = useState<string | null>(null)
-    const inactive = disabled || readonly
+    const inactive = disabled || readOnly
+
+    const gesture = useChangeGesture(
+      value,
+      { onChangeStart, onChangeEnd, changeEndDelay },
+      inactive,
+    )
 
     // --- interpret props ---
     const format = formatProp ?? defaultFormat
@@ -339,18 +392,25 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         // Deliberately unclamped: clamping here would make "1500" impossible
         // to type into an input whose max is 100.
         const parsed = parse(next)
-        if (Number.isFinite(parsed)) onChange?.(parsed)
+        if (!Number.isFinite(parsed)) return
+        if (parsed !== value) {
+          gesture.pulse('keyboard')
+          gesture.changed(parsed)
+        }
+        onChange?.(parsed)
       },
-      [inactive, parse, onChange],
+      [inactive, parse, onChange, value, gesture],
     )
 
     const changeValue = useCallback(
       (next: number) => {
         if (inactive) return
         setDraft(null)
-        if (next !== value) onChange?.(next)
+        if (next === value) return
+        gesture.changed(next)
+        onChange?.(next)
       },
-      [inactive, value, onChange],
+      [inactive, value, onChange, gesture],
     )
 
     const commitDraft = useCallback(() => {
@@ -362,9 +422,25 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
       })
       // Text with no number in it is not a value. Dropping the draft puts the
       // input back to what it was showing.
-      if (committed === null) setDraft(null)
-      else changeValue(committed)
-    }, [draft, inactive, parse, clampValue, min, max, changeValue])
+      if (committed === null) {
+        setDraft(null)
+        return
+      }
+      // The typing was a gesture of its own, and committing is where it ends.
+      if (committed !== value) gesture.pulse('keyboard')
+      changeValue(committed)
+      gesture.end()
+    }, [
+      draft,
+      inactive,
+      parse,
+      clampValue,
+      min,
+      max,
+      changeValue,
+      value,
+      gesture,
+    ])
 
     const nudge = useCallback(
       (
@@ -385,6 +461,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         const direction = wheelDirection(event)
         if (!wheel || inactive || direction === null) return
         event.preventDefault()
+        gesture.pulse('wheel')
         nudge(direction, wheel, event)
       },
       { requireFocus: true },
@@ -398,7 +475,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         step,
         scale,
         disabled,
-        readonly,
+        readOnly,
         clampValue,
         range,
         rawRange,
@@ -408,6 +485,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         outOfRange,
         dragSensitivity,
         pointerLock,
+        dragCursor,
         selectOnFocus,
         unformatOnFocus,
         keepCaretOnStep,
@@ -430,7 +508,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         step,
         scale,
         disabled,
-        readonly,
+        readOnly,
         clampValue,
         range,
         rawRange,
@@ -443,6 +521,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         drag,
         dragSensitivity,
         pointerLock,
+        dragCursor,
         selectOnFocus,
         unformatOnFocus,
         keepCaretOnStep,
@@ -456,7 +535,14 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
       ],
     )
 
-    useImperativeHandle(forwardedRef, () => {
+    // Composed once, so React attaches the refs a single time instead of
+    // detaching and re-attaching on every render.
+    const rootRefCallback = useComposedRefs<HTMLDivElement>(
+      forwardedRef,
+      wheelRefCallback,
+    )
+
+    useImperativeHandle(actionsRef, () => {
       return {
         focus() {
           if (!disabled) inputRef.current?.focus()
@@ -467,18 +553,47 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
       }
     }, [disabled])
 
+    const pressed = useRef(false)
+    const gestureContext = useMemo(
+      () => ({
+        press: () => {
+          if (inactive) return
+          gesture.hold('pointer')
+          // A press on a stepper reaches `Stepper` too; one release will do.
+          if (pressed.current) return
+          pressed.current = true
+          // Released wherever the pointer ends up: the stepper drag captures
+          // it, and a press that wanders off the button still ends.
+          const release = () => {
+            pressed.current = false
+            gesture.end()
+            window.removeEventListener('pointerup', release)
+            window.removeEventListener('pointercancel', release)
+          }
+          window.addEventListener('pointerup', release)
+          window.addEventListener('pointercancel', release)
+        },
+        key: () => {
+          if (!inactive) gesture.pulse('keyboard')
+        },
+      }),
+      [gesture, inactive],
+    )
+
     return (
       <NumberInputProvider value={context}>
-        <div
-          ref={wheelRefCallback}
-          className={className}
-          data-disabled={disabled ? '' : undefined}
-          data-readonly={readonly ? '' : undefined}
-          style={style}
-          {...props}
-        >
-          {children}
-        </div>
+        <NumberInputGestureProvider value={gestureContext}>
+          <div
+            ref={rootRefCallback}
+            className={className}
+            data-disabled={disabled ? '' : undefined}
+            data-readonly={readOnly ? '' : undefined}
+            style={style}
+            {...props}
+          >
+            {children}
+          </div>
+        </NumberInputGestureProvider>
       </NumberInputProvider>
     )
   },

package/src/components/Piano/index.tsx

@@ -3,6 +3,7 @@ import {
   CSSProperties,
   forwardRef,
   ReactNode,
+  Ref,
   useEffect,
   useImperativeHandle,
   useMemo,
@@ -11,20 +12,24 @@ import {
 } from 'react'
 
 import {
-  blackKeyWidth,
   createPianoInput,
-  fitWhiteKeyWidth,
-  getNoteRangeArray,
   type KeyboardShortcuts,
   type KeyboardShortcutsScope,
   notePosition,
-  pianoWidth,
   type NoteRange,
   type PianoInputInstance,
   type PianoLayout,
 } from '@tremolo-ui/dom'
+import {
+  blackKeyWidth,
+  fitWhiteKeyWidth,
+  getNoteRangeArray,
+  pianoWidth,
+} from '@tremolo-ui/dom/internal'
 import { isWhiteKey, noteKey } from '@tremolo-ui/functions'
 
+import { useComposedRefs } from '../../compose-refs'
+
 /**
  * What {@link PianoProps.keyProps} may return for one key.
  *
@@ -155,6 +160,12 @@ export interface PianoProps {
   onPlayNote?: (note: number, velocity?: number) => void
   /** Called once everything holding a note has let go of it. */
   onStopNote?: (note: number) => void
+
+  /**
+   * Receives `playNote` and `stopNote`, which press and release a key as the
+   * pointer or the keyboard would. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<PianoMethods>
 }
 
 export interface PianoMethods {
@@ -165,7 +176,7 @@ export interface PianoMethods {
 type Props = PianoProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof PianoProps>
 
-export const Root = /* @__PURE__ */ forwardRef<PianoMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   function Root(
     {
       noteRange,
@@ -185,6 +196,7 @@ export const Root = /* @__PURE__ */ forwardRef<PianoMethods, Props>(
       classes,
       onPlayNote,
       onStopNote,
+      actionsRef,
       ...props
     },
     forwardedRef,
@@ -295,8 +307,13 @@ export const Root = /* @__PURE__ */ forwardRef<PianoMethods, Props>(
       return () => resizeObserver.disconnect()
     }, [resizable, node, first, last, keyGap, blackKeyWidthRatio])
 
-    useImperativeHandle(
+    const rootRefCallback = useComposedRefs<HTMLDivElement>(
       forwardedRef,
+      setNode,
+    )
+
+    useImperativeHandle(
+      actionsRef,
       () => ({
         playNote: (note, velocity) =>
           instanceRef.current?.noteOn(note, { source: 'api', velocity }),
@@ -308,7 +325,7 @@ export const Root = /* @__PURE__ */ forwardRef<PianoMethods, Props>(
 
     return (
       <div
-        ref={setNode}
+        ref={rootRefCallback}
         className={className}
         data-resizable={resizable ? '' : undefined}
         role="group"

package/src/components/PointsEditor/Container.tsx

@@ -1,6 +1,6 @@
 import { ComponentPropsWithoutRef, forwardRef } from 'react'
 
-import { POINT_AXIS, wheelMove } from '@tremolo-ui/dom'
+import { POINT_AXIS, wheelMove } from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
 import { useDragValue } from '../../hooks/useDragValue'

package/src/components/PointsEditor/Point.tsx

@@ -8,17 +8,21 @@ import {
 } from 'react'
 
 import {
-  arrowKeyMove,
-  clampPoint,
+  type ChangeSource,
   type InputEventOption,
   type ModifierValue,
-  POINT_AXIS,
   type PointPosition,
   type PointsEditorPoint,
-  selectModifier,
 } from '@tremolo-ui/dom'
+import {
+  arrowKeyMove,
+  clampPoint,
+  POINT_AXIS,
+  selectModifier,
+} from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
+import { useChangeGesture } from '../../hooks/_internal/useChangeGesture'
 import { useDragValue } from '../../hooks/useDragValue'
 import { useCheckPlacement } from '../_util/Placement'
 import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
@@ -49,8 +53,8 @@ export interface PointsEditorPointProps<T extends PointPosition> {
 
   /** Overrides the `disabled` of `PointsEditor.Root`. */
   disabled?: boolean
-  /** Overrides the `readonly` of `PointsEditor.Root`. */
-  readonly?: boolean
+  /** Overrides the `readOnly` of `PointsEditor.Root`. */
+  readOnly?: boolean
 
   /** Overrides the `wheel` of `PointsEditor.Root`. */
   wheel?: ModifierValue<InputEventOption> | null
@@ -70,10 +74,25 @@ export interface PointsEditorPointProps<T extends PointPosition> {
    * arrow keys or the wheel, including when it moves along with a selection.
    */
   onChange?: (value: PointPosition) => void
-  /** Called when a drag on this point starts, with where the point is. */
-  onDragStart?: (value: PointPosition) => void
-  /** Called when that drag ends, with where the point is. */
-  onDragEnd?: (value: PointPosition) => void
+  /**
+   * Called when a change of this point starts — a drag on it, the first wheel
+   * notch or arrow key while it has the focus — with where it is and what the
+   * change is made with. The points that move along with a selection report
+   * through `onChange` only: the change belongs to the point being operated.
+   */
+  onChangeStart?: (value: PointPosition, source: ChangeSource) => void
+  /**
+   * Called when that change ends, with where the point is: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: PointPosition, 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
 
   style?: CSSProperties & CSSVariables<'color' | 'translate'>
 }
@@ -98,15 +117,16 @@ export function Point<T extends PointPosition>({
   color,
 
   disabled: _disabled,
-  readonly: _readonly,
+  readOnly: _readOnly,
   wheel: _wheel,
   keyboard: _keyboard,
   'aria-label': ariaLabel,
   'aria-valuetext': ariaValuetext,
 
   onChange,
-  onDragStart,
-  onDragEnd,
+  onChangeStart,
+  onChangeEnd,
+  changeEndDelay,
 
   className,
   style,
@@ -118,9 +138,9 @@ export function Point<T extends PointPosition>({
   Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorPointProps<T>>) {
   const {
     containerRef,
-    externalStyles,
+    dragCursor,
     disabled: rootDisabled,
-    readonly: rootReadonly,
+    readOnly: rootReadOnly,
     wheel: rootWheel,
     keyboard: rootKeyboard,
     dragSensitivity,
@@ -133,8 +153,8 @@ export function Point<T extends PointPosition>({
   const selected = selection.includes(id)
 
   const disabled = _disabled ?? rootDisabled
-  const readonly = _readonly ?? rootReadonly
-  const inactive = disabled || readonly
+  const readOnly = _readOnly ?? rootReadOnly
+  const inactive = disabled || readOnly
   // `null` means "no event" and has to survive the fallback, so `??` is not
   // enough: only an omitted prop inherits from the root.
   const wheel = _wheel === undefined ? rootWheel : _wheel
@@ -142,6 +162,19 @@ export function Point<T extends PointPosition>({
 
   useCheckPlacement('PointsEditor.Point', 'PointsEditor.Container')
 
+  const current = clampPoint(value, min, max)
+  const gesture = useChangeGesture(
+    current,
+    { onChangeStart, onChangeEnd, changeEndDelay },
+    inactive,
+  )
+  // Every move reaches the point through here, whatever moved it, so the
+  // last one is what `onChangeEnd` gives.
+  const handleChange = (next: PointPosition) => {
+    gesture.changed(next)
+    onChange?.(next)
+  }
+
   // Compared against the focus below, so the point needs its own element.
   const [element, setElement] = useState<HTMLDivElement | null>(null)
   const xInputRef = useRef<HTMLInputElement>(null)
@@ -155,9 +188,10 @@ export function Point<T extends PointPosition>({
     min,
     max,
     readonly: inactive,
-    onChange,
+    onChange: onChange ? handleChange : undefined,
     element,
     wheel,
+    beforeWheel: () => gesture.pulse('wheel'),
   })
   useEffect(() => {
     registration.current = {
@@ -165,9 +199,10 @@ export function Point<T extends PointPosition>({
       min,
       max,
       readonly: inactive,
-      onChange,
+      onChange: onChange ? handleChange : undefined,
       element,
       wheel,
+      beforeWheel: () => gesture.pulse('wheel'),
     }
   })
 
@@ -186,7 +221,7 @@ export function Point<T extends PointPosition>({
       baseElementRef: containerRef,
       sensitivity: (state) =>
         selectModifier(dragSensitivity, state.event).value,
-      cursor: inactive ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : dragCursor,
       shouldStart: () => !disabled,
       // The value is a move rather than a position: the point keeps the offset
       // it was grabbed at, and everything else selected moves with it by the
@@ -204,14 +239,11 @@ export function Point<T extends PointPosition>({
         pointerOrigin.current = { x, y }
         xInputRef.current?.focus()
 
-        if (inactive) return
-        onDragStart?.(clampPoint(value, min, max))
+        if (!inactive) gesture.hold('pointer')
       },
       onDragEnd: () => {
         pointerOrigin.current = null
-
-        if (inactive) return
-        onDragEnd?.(clampPoint(value, min, max))
+        gesture.end()
       },
     })
 
@@ -229,6 +261,7 @@ export function Point<T extends PointPosition>({
     if (!move) return
     event.preventDefault()
     if (!onChange || inactive || !keyboard) return
+    gesture.pulse('keyboard')
     editor.nudgePoint(
       id,
       move.axis === 0 ? 'x' : 'y',
@@ -238,8 +271,6 @@ export function Point<T extends PointPosition>({
     )
   }
 
-  const current = clampPoint(value, min, max)
-
   return (
     // The visual point has two values, so its semantics live on the two range
     // inputs nested inside it rather than on this drag handle.
@@ -248,7 +279,7 @@ export function Point<T extends PointPosition>({
       ref={refCallback}
       className={className}
       data-disabled={disabled ? '' : undefined}
-      data-readonly={readonly ? '' : undefined}
+      data-readonly={readOnly ? '' : undefined}
       // A press lands on the point, which cannot hold focus, and the browser
       // answers that by clearing the focus to the body — undoing the focus the
       // drag just gave the input. Taking the focus here keeps it inside, and
@@ -294,12 +325,12 @@ export function Point<T extends PointPosition>({
           max={max?.[axis] ?? 1}
           step="any"
           disabled={disabled}
-          aria-readonly={readonly}
+          aria-readonly={readOnly}
           aria-orientation={axis === 'x' ? 'horizontal' : 'vertical'}
           aria-label={perAxis(ariaLabel, axis) ?? axis}
           aria-valuetext={perAxis(ariaValuetext, axis)}
           onChange={(event) => {
-            if (readonly) {
+            if (readOnly) {
               event.currentTarget.value = String(current[axis])
               return
             }