@tremolo-ui/react 0.7.0 → 0.9.0

package/src/components/NumberInput/StepperButton.tsx

@@ -2,7 +2,11 @@ import { ComponentPropsWithoutRef, ReactNode, CSSProperties } from 'react'
 
 import { useLongPress } from '../../hooks/useLongPress'
 
-import { useNumberInputContext, useStepperContext } from './context'
+import {
+  useNumberInputContext,
+  useNumberInputGesture,
+  useStepperContext,
+} from './context'
 
 import type { CSSVariables } from '../../css-variables'
 
@@ -37,17 +41,17 @@ export function StepperButton({
   variant: 'increment' | 'decrement'
   icon: ReactNode
 }) {
-  const { step, disabled, readonly, atMin, atMax, nudge } =
+  const { step, disabled, readOnly, atMin, atMax, nudge } =
     useNumberInputContext()
   const stepper = useStepperContext()
+  const gesture = useNumberInputGesture()
 
-  // Not memoized: the callback reads `draggingRef.current`, which the compiler
-  // cannot line up with a manual dependency list. `useLongPress` only ever
-  // calls it through a ref, so a fresh identity per render costs nothing.
+  // Not memoized: `useLongPress` only ever calls it through a ref, so a fresh
+  // identity per render costs nothing.
   const press = useLongPress(() => {
     // Once the pointer has actually travelled, the drag on `Stepper` owns the
     // value; repeating on top of it would move it twice.
-    if (stepper?.draggingRef.current) return
+    if (stepper?.moved()) return
     nudge(direction, ['raw', step])
   })
 
@@ -65,10 +69,13 @@ export function StepperButton({
       data-disabled={
         disabled || (direction > 0 ? atMax : atMin) ? '' : undefined
       }
-      data-readonly={readonly ? '' : undefined}
+      data-readonly={readOnly ? '' : undefined}
       style={style}
       onPointerDown={(event) => {
-        if (!disabled && !readonly) press(event)
+        if (!disabled && !readOnly) {
+          gesture?.press()
+          press(event)
+        }
         onPointerDown?.(event)
       }}
       {...props}

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,9 +103,30 @@ 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 = {
-  draggingRef: RefObject<boolean>
+  /** Whether the drag in progress has moved the value. */
+  moved: () => boolean
 }
 
 const StepperContext =

package/src/components/NumberInput/index.tsx

@@ -1,7 +1,9 @@
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
   ReactNode,
+  Ref,
   useCallback,
   useImperativeHandle,
   useMemo,
@@ -10,23 +12,30 @@ import {
 } from 'react'
 
 import {
-  applyDelta,
+  type ChangeSource,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   InputEventOption,
   ModifierState,
   type ModifierValue,
-  selectModifier,
 } from '@tremolo-ui/dom'
-import { linearScale, type Scale, type ValueRange } from '@tremolo-ui/functions'
-
+import {
+  commitNumberInputText,
+  numberInputBounds,
+  numberInputRanges,
+  nudgeNumberInput,
+  parseNumberText,
+  wheelDirection,
+} 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 {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from '../../input-event'
 
-import { NumberInputProvider } from './context'
+import { NumberInputGestureProvider, NumberInputProvider } from './context'
 import { DecrementStepper } from './DecrementStepper'
 import { IncrementStepper } from './IncrementStepper'
 import { InputField } from './InputField'
@@ -83,6 +92,9 @@ export interface NumberInputProps {
    * Read a value back out of the text. Has to undo `format`.
    *
    * Text with no number in it reads as `NaN`, which leaves the value alone.
+   * The default, `parseNumberText` from `@tremolo-ui/dom`, reads the number
+   * with the unit around it left out, and is `NaN` for one it cannot read
+   * whole: `1,000`, `1:30`, or a number with a unit in front, such as `L 30`.
    */
   parse?: (text: string) => number
 
@@ -157,10 +169,17 @@ 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,
-   * `'number'` only the leading number, leaving whatever the format appended,
+   * `'number'` only the number, leaving the unit the format put around it,
    * and `'none'` leaves the caret where the click put it.
    * @default 'none'
    */
@@ -214,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
@@ -222,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
@@ -237,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 {
@@ -244,24 +291,12 @@ export interface NumberInputMethods {
   blur: () => void
 }
 
-/**
- * A number at the start of the text, and nothing read after it. A half-typed
- * entry still yields the number in front of it, but text with no number is
- * `NaN` rather than 0, so that "unreadable" and "the user typed 0" stay apart.
- */
-const LEADING_NUMBER = /^\s*([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)/
-
 const defaultFormat = (value: number) => String(value)
 
-const defaultParse = (text: string) => {
-  const match = text.match(LEADING_NUMBER)
-  return match ? Number(match[1]) : NaN
-}
-
 type Props = NumberInputProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof NumberInputProps>
 
-export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       value,
@@ -277,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,
@@ -298,36 +338,25 @@ 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
-    const parse = parseProp ?? defaultParse
+    const parse = parseProp ?? parseNumberText
 
-    // Normalized input needs a finite span even when an end is unbounded or
-    // the caller opted out of clamping. Safe integers provide one without
-    // overflowing the span calculation used by a scale.
-    const range: ValueRange = useMemo(
-      () => ({
-        min: (clampValue ? min : undefined) ?? Number.MIN_SAFE_INTEGER,
-        max: (clampValue ? max : undefined) ?? Number.MAX_SAFE_INTEGER,
-        step,
-        scale,
-      }),
+    const { normalized: range, raw: rawRange } = useMemo(
+      () => numberInputRanges({ min, max, step, scale, clampValue }),
       [clampValue, min, max, step, scale],
     )
-
-    // Raw input does not need a finite span for normalization, so its open
-    // ends can cover every finite JavaScript number instead of stopping at the
-    // safe-integer range.
-    const rawRange: ValueRange = useMemo(
-      () => ({
-        min: (clampValue ? min : undefined) ?? -Number.MAX_VALUE,
-        max: (clampValue ? max : undefined) ?? Number.MAX_VALUE,
-        step,
-        scale,
-      }),
-      [clampValue, min, max, step, scale],
+    const ranges = useMemo(
+      () => ({ normalized: range, raw: rawRange }),
+      [range, rawRange],
     )
 
     // The pipeline range stands in the safe-integer range when an end is
@@ -351,9 +380,9 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
 
     const text = draft ?? format(value)
     const editing = draft !== null
-    const outOfRange =
-      !editing &&
-      ((min !== undefined && value < min) || (max !== undefined && value > max))
+    const bounds = numberInputBounds(value, { min, max, clampValue })
+    const { atMin, atMax } = bounds
+    const outOfRange = !editing && bounds.outOfRange
 
     // --- internal functions ---
     const handleDraft = useCallback(
@@ -363,35 +392,55 @@ 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(() => {
       if (draft === null || inactive) return
-      const parsed = parse(draft)
+      const committed = commitNumberInputText(draft, parse, {
+        min,
+        max,
+        clampValue,
+      })
       // Text with no number in it is not a value. Dropping the draft puts the
-      // input back to what it was showing, rather than committing a zero the
-      // user never typed.
-      if (!Number.isFinite(parsed)) {
+      // input back to what it was showing.
+      if (committed === null) {
         setDraft(null)
         return
       }
-      let committed = parsed
-      if (clampValue && min !== undefined) committed = Math.max(committed, min)
-      if (clampValue && max !== undefined) committed = Math.min(committed, max)
+      // The typing was a gesture of its own, and committing is where it ends.
+      if (committed !== value) gesture.pulse('keyboard')
       changeValue(committed)
-    }, [draft, inactive, parse, clampValue, min, max, changeValue])
+      gesture.end()
+    }, [
+      draft,
+      inactive,
+      parse,
+      clampValue,
+      min,
+      max,
+      changeValue,
+      value,
+      gesture,
+    ])
 
     const nudge = useCallback(
       (
@@ -399,26 +448,21 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         option: ModifierValue<InputEventOption>,
         modifiers?: ModifierState,
       ) => {
-        const [mode] = selectModifier(option, modifiers).value
         changeValue(
-          applyDelta(
-            value,
-            direction,
-            option,
-            mode === 'raw' ? rawRange : range,
-            modifiers,
-          ),
+          nudgeNumberInput(value, direction, option, ranges, modifiers),
         )
       },
-      [changeValue, value, rawRange, range],
+      [changeValue, value, ranges],
     )
 
     // --- hooks ---
     const wheelRefCallback = useWheel<HTMLDivElement>(
       (event) => {
-        if (!wheel || inactive || event.deltaY === 0) return
+        const direction = wheelDirection(event)
+        if (!wheel || inactive || direction === null) return
         event.preventDefault()
-        nudge(-Math.sign(event.deltaY), wheel, event)
+        gesture.pulse('wheel')
+        nudge(direction, wheel, event)
       },
       { requireFocus: true },
     )
@@ -431,7 +475,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         step,
         scale,
         disabled,
-        readonly,
+        readOnly,
         clampValue,
         range,
         rawRange,
@@ -441,12 +485,13 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         outOfRange,
         dragSensitivity,
         pointerLock,
+        dragCursor,
         selectOnFocus,
         unformatOnFocus,
         keepCaretOnStep,
         blurOnEnter,
-        atMin: clampValue && min !== undefined && value <= min,
-        atMax: clampValue && max !== undefined && value >= max,
+        atMin,
+        atMax,
         drag,
         format,
         parse,
@@ -463,7 +508,7 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         step,
         scale,
         disabled,
-        readonly,
+        readOnly,
         clampValue,
         range,
         rawRange,
@@ -471,9 +516,12 @@ export const Root = /* @__PURE__ */ forwardRef<NumberInputMethods, Props>(
         text,
         editing,
         outOfRange,
+        atMin,
+        atMax,
         drag,
         dragSensitivity,
         pointerLock,
+        dragCursor,
         selectOnFocus,
         unformatOnFocus,
         keepCaretOnStep,
@@ -487,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()
@@ -498,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>
     )
   },