@tremolo-ui/react 0.7.0 → 0.9.0

package/src/components/Knob/index.tsx

@@ -3,6 +3,7 @@ import {
   CSSProperties,
   forwardRef,
   ReactNode,
+  Ref,
   useCallback,
   useImperativeHandle,
   useMemo,
@@ -10,38 +11,39 @@ import {
 } from 'react'
 
 import {
-  applyDelta,
   type AxisOptions,
+  type ChangeSource,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   type InputEventOption,
+  knobAngles,
   type ModifierValue,
-  selectModifier,
   type XY,
 } from '@tremolo-ui/dom'
+import {
+  applyDelta,
+  arrowKeyDirection,
+  cssLength,
+  selectModifier,
+  wheelDirection,
+} from '@tremolo-ui/dom/internal'
 import { linearScale, type Scale, type ValueRange } 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 { cssLength } from '../_util/css-length'
 
 import { ActiveLine } from './ActiveLine'
-import { calcAngles, KnobProvider } from './context'
+import { KnobProvider } from './context'
 import { InactiveLine } from './InactiveLine'
 import { SVGRoot } from './SVGRoot'
 import { Thumb } from './Thumb'
 
 import type { CSSVariables } from '../../css-variables'
 
-const defaultExternalStyles: KnobProps['externalStyles'] = {
-  cursor: 'grabbing',
-}
-
 export interface KnobProps {
   /** The current value. The knob shows only this, so update it from `onChange`. */
   value: number
@@ -68,10 +70,10 @@ export interface KnobProps {
    */
   scale?: Scale
   /**
-   * The value a double click restores, while `enableDoubleClickDefault` is on.
-   * @default min
+   * The value a double click restores. `null` turns the double click off.
+   * @default startValue
    */
-  defaultValue?: number
+  resetValue?: number | null
 
   /**
    * Where the active arc starts. Put it at the centre of a bipolar control,
@@ -90,11 +92,9 @@ export interface KnobProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the knob.
    *
-   * @default { cursor: 'grabbing' }
+   * @default 'grabbing'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor']
-  }
+  dragCursor?: CSSProperties['cursor']
   /**
    * How much one notch of the wheel moves the value. It only acts while the
    * focus is inside, so that scrolling the page past the knob leaves it alone.
@@ -157,11 +157,6 @@ export interface KnobProps {
    * @default { default: ['raw', 1], shift: ['raw', 0.1] }
    */
   keyboard?: ModifierValue<InputEventOption> | null
-  /**
-   * Restore `defaultValue` on a double click.
-   * @default true
-   */
-  enableDoubleClickDefault?: boolean
 
   /**
    * Make the knob unchangeable and remove it from the tab order.
@@ -172,7 +167,7 @@ export interface KnobProps {
    * Make the knob unchangeable while leaving it focusable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean
+  readOnly?: boolean
 
   /**
    * How far the knob turns from `min` to `max`, in degrees, centred on the
@@ -186,6 +181,25 @@ export interface KnobProps {
    * click moves it.
    */
   onChange?: (value: number) => void
+  /**
+   * Called when a change of the value starts — a drag, a double click, 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: 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: 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 knob renders exactly what you compose here; there is no default
@@ -203,6 +217,13 @@ export interface KnobProps {
   children: ReactNode
 
   style?: CSSProperties & CSSVariables<'knob-size'>
+
+  /**
+   * Receives `focus` and `blur`. They do nothing while the knob is disabled,
+   * where the element's own `focus()` would still focus it. `ref` reaches the
+   * root element itself.
+   */
+  actionsRef?: Ref<KnobMethods>
 }
 
 export interface KnobMethods {
@@ -218,7 +239,7 @@ type Props = KnobProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KnobProps>
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
   (
     {
       value,
@@ -226,33 +247,35 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
       max,
       step = 1,
       scale = linearScale,
-      defaultValue = min,
+      resetValue,
       startValue = min,
       size,
-      externalStyles: _externalStyles,
+      dragCursor = 'grabbing',
       wheel = DEFAULT_WHEEL_OPTIONS,
       keyboard = DEFAULT_KEYBOARD_OPTIONS,
       dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       pointerLock = false,
-      enableDoubleClickDefault = true,
       disabled = false,
-      readonly = false,
+      readOnly = false,
       angleRange = 270,
       onChange,
+      onChangeStart,
+      onChangeEnd,
+      changeEndDelay,
       onKeyDown,
       onPointerDown,
       onDoubleClick,
       className,
       style,
       children,
+      actionsRef,
       ...props
     }: Props,
     forwardedRef,
   ) => {
-    const elmRef = useRef<HTMLElement | SVGElement>(null)
+    const elmRef = useRef<HTMLDivElement>(null)
 
-    const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
-    const inactive = disabled || readonly
+    const inactive = disabled || readOnly
 
     // --- internal functions ---
     const range: ValueRange = useMemo(
@@ -262,17 +285,29 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
 
     useCheckSteps({ component: 'Knob', range, keyboard, wheel })
 
+    const gesture = useChangeGesture(
+      value,
+      { onChangeStart, onChangeEnd, changeEndDelay },
+      inactive,
+    )
+    const change = useCallback(
+      (next: number) => {
+        gesture.changed(next)
+        onChange?.(next)
+      },
+      [gesture, onChange],
+    )
+
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLOrSVGElement>) => {
         if (!keyboard || !onChange || inactive) return
-        const key = event.key
-        if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
-          event.preventDefault()
-          const direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
-          onChange(applyDelta(value, direction, keyboard, range, event))
-        }
+        const direction = arrowKeyDirection(event.key)
+        if (direction === null) return
+        event.preventDefault()
+        gesture.pulse('keyboard')
+        change(applyDelta(value, direction, keyboard, range, event))
       },
-      [keyboard, onChange, inactive, value, range],
+      [keyboard, onChange, inactive, value, range, gesture, change],
     )
 
     // --- hooks ---
@@ -293,25 +328,35 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
       sensitivity: (state) =>
         selectModifier(dragSensitivity, state.event).value,
       threshold: 1,
-      cursor: inactive ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : dragCursor,
       pointerLock: inactive ? false : pointerLock,
       shouldStart: () => !inactive,
       onChange: (v) => {
         if (inactive) return
-        onChange?.(v[1])
+        change(v[1])
+      },
+      onDragStart: () => {
+        if (!inactive) gesture.hold('pointer')
       },
+      onDragEnd: () => gesture.end(),
     })
 
     const wheelRefCallback = useWheel<HTMLElement>((event) => {
       if (!wheel || inactive) return
+      // A notch the knob does not read — a sideways scroll — is left to the
+      // page rather than swallowed.
+      const direction = wheelDirection(event)
+      if (direction === null) return
       event.preventDefault()
-      if (!onChange || event.deltaY === 0) return
-      onChange(applyDelta(value, -Math.sign(event.deltaY), wheel, range, event))
+      if (!onChange) return
+      gesture.pulse('wheel')
+      change(applyDelta(value, direction, wheel, range, 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<HTMLElement | SVGElement>(
+    const rootRefCallback = useComposedRefs<HTMLDivElement>(
+      forwardedRef,
       elmRef,
       dragRefCallback,
       wheelRefCallback,
@@ -319,10 +364,10 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
 
     const context = useMemo(() => {
       const config = { value, min, max, step, scale, startValue, angleRange }
-      return { ...config, ...calcAngles(config) }
+      return { ...config, ...knobAngles(config) }
     }, [value, min, max, step, scale, startValue, angleRange])
 
-    useImperativeHandle(forwardedRef, () => {
+    useImperativeHandle(actionsRef, () => {
       return {
         focus() {
           if (!disabled) elmRef.current?.focus()
@@ -344,9 +389,9 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
           aria-valuemin={min}
           aria-valuemax={max}
           aria-disabled={disabled}
-          aria-readonly={readonly}
+          aria-readonly={readOnly}
           data-disabled={disabled ? '' : undefined}
-          data-readonly={readonly ? '' : undefined}
+          data-readonly={readOnly ? '' : undefined}
           data-dragging={dragging ? '' : undefined}
           style={
             {
@@ -356,8 +401,10 @@ export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
           }
           onPointerDown={onPointerDown}
           onDoubleClick={(event) => {
-            if (!inactive && enableDoubleClickDefault && onChange) {
-              onChange(defaultValue)
+            if (!inactive && resetValue !== null && onChange) {
+              gesture.instant('doubleClick', () =>
+                change(resetValue ?? startValue),
+              )
             }
             onDoubleClick?.(event)
           }}

package/src/components/NumberInput/InputField.tsx

@@ -7,9 +7,15 @@ import {
   useState,
 } from 'react'
 
+import {
+  caretAtDecimalOffset,
+  caretDecimalOffset,
+  numberSpan,
+} from '@tremolo-ui/dom/internal'
+
 import { useComposedRefs } from '../../compose-refs'
 
-import { useNumberInputContext } from './context'
+import { useNumberInputContext, useNumberInputGesture } from './context'
 
 // The value belongs to `NumberInput.Root`, and the field is always text.
 type Props = Omit<
@@ -17,25 +23,6 @@ type Props = Omit<
   'type' | 'value' | 'defaultValue'
 >
 
-/** The leading number of the displayed text, whatever the format put around it. */
-const NUMBER_PREFIX = /^\s*-?[\d.,]*/
-
-const numberEnd = (text: string) =>
-  text.match(NUMBER_PREFIX)?.[0].length ?? text.length
-
-/**
- * The index the caret is measured against: the decimal point, or where one
- * would go if the number has none.
- *
- * Measuring from an end instead would slide the caret across a digit whenever
- * the number changed length — `9.9` to `10.0` gains a character in front, `10`
- * to `9` loses one — which is exactly what stepping does.
- */
-const decimalAnchor = (text: string) => {
-  const dot = text.indexOf('.')
-  return dot === -1 ? numberEnd(text) : dot
-}
-
 /**
  * The text field of a `NumberInput`, and the only place the value can be typed.
  *
@@ -47,7 +34,7 @@ const decimalAnchor = (text: string) => {
  */
 export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
   function InputField(
-    { className, style, onFocus, onBlur, onKeyDown, ...props },
+    { className, style, onChange, onFocus, onBlur, onKeyDown, ...props },
     forwardedRef,
   ) {
     const {
@@ -56,7 +43,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
       max,
       step,
       disabled,
-      readonly,
+      readOnly,
       keyboard,
       selectOnFocus,
       unformatOnFocus,
@@ -71,6 +58,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
       inputRef,
     } = useNumberInputContext()
 
+    const gesture = useNumberInputGesture()
     const [focused, setFocused] = useState(false)
 
     // Only until the first keystroke: from then on the draft is the user's own
@@ -87,10 +75,8 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
       if (selectOnFocus === 'all') {
         input.setSelectionRange(0, input.value.length)
       } else {
-        input.setSelectionRange(
-          0,
-          input.value.match(NUMBER_PREFIX)?.[0].length ?? 0,
-        )
+        const span = numberSpan(input.value)
+        if (span) input.setSelectionRange(span.start, span.end)
       }
       // Deliberately not re-run as the text changes: that would drag the
       // selection back over what the user is typing.
@@ -114,8 +100,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
       // caret has not moved either, since the key press was prevented.
       if (!input || input.value === pending.from) return
 
-      const place = decimalAnchor(input.value) + pending.offset
-      const caret = Math.max(0, Math.min(place, numberEnd(input.value)))
+      const caret = caretAtDecimalOffset(input.value, pending.offset)
       input.setSelectionRange(caret, caret)
     })
 
@@ -135,11 +120,11 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
         role="spinbutton"
         value={shown}
         disabled={disabled}
-        readOnly={readonly}
+        readOnly={readOnly}
         aria-disabled={disabled}
-        aria-readonly={readonly}
+        aria-readonly={readOnly}
         data-disabled={disabled ? '' : undefined}
-        data-readonly={readonly ? '' : undefined}
+        data-readonly={readOnly ? '' : undefined}
         aria-valuenow={value}
         aria-valuemin={min}
         aria-valuemax={max}
@@ -154,6 +139,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
           // stepped one no longer means anything.
           caretAfterStep.current = null
           setDraft(event.currentTarget.value)
+          onChange?.(event)
         }}
         onFocus={(event) => {
           setFocused(true)
@@ -174,7 +160,7 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
           } else if (
             keyboard &&
             !disabled &&
-            !readonly &&
+            !readOnly &&
             (key === 'ArrowUp' || key === 'ArrowDown') &&
             // Arrow keys pick a candidate while an IME is converting. Stepping
             // the value there would fight the conversion, and moving the caret
@@ -185,10 +171,11 @@ export const InputField = /* @__PURE__ */ forwardRef<HTMLInputElement, Props>(
             const input = event.currentTarget
             if (keepCaretOnStep && input.selectionStart !== null) {
               caretAfterStep.current = {
-                offset: input.selectionStart - decimalAnchor(input.value),
+                offset: caretDecimalOffset(input.value, input.selectionStart),
                 from: input.value,
               }
             }
+            gesture?.key()
             nudge(key === 'ArrowUp' ? 1 : -1, keyboard, event)
           }
           onKeyDown?.(event)

package/src/components/NumberInput/Stepper.tsx

@@ -1,136 +1,112 @@
-import { ComponentPropsWithoutRef, forwardRef, useMemo, useRef } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  forwardRef,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
 
 import {
-  applyDelta,
-  type InputEventOption,
-  mapModifier,
-  selectModifier,
-} from '@tremolo-ui/dom'
+  createStepperDrag,
+  type StepperDragInstance,
+} from '@tremolo-ui/dom/internal'
 
 import { useComposedRefs } from '../../compose-refs'
-import { useDrag } from '../../hooks/useDrag'
 
-import { StepperProvider, useNumberInputContext } from './context'
+import {
+  StepperProvider,
+  useNumberInputContext,
+  useNumberInputGesture,
+} from './context'
 
 type Props = ComponentPropsWithoutRef<'div'>
 
 /**
  * The area the steppers sit in, and a drag handle in its own right: dragging it
- * up and down moves the value one `step` every `drag` pixels.
+ * up and down moves the value one `step` every `drag` pixels. The counting is
+ * `createStepperDrag` in the core.
  *
  * The drag lives here rather than on `InputField` because `createDrag` turns
  * off text selection on whatever element it is attached to.
  */
 export const Stepper = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
-  function Stepper({ className, style, children, ...props }, forwardedRef) {
+  function Stepper(
+    { className, style, children, onPointerDown, ...props },
+    forwardedRef,
+  ) {
     const {
       value,
-      step,
       disabled,
-      readonly,
+      readOnly,
       drag,
       dragSensitivity,
       pointerLock,
+      dragCursor,
       rawRange,
       changeValue,
     } = useNumberInputContext()
-    const inactive = disabled || readonly
-
-    /**
-     * The sensitivity as an amount per `drag` pixels, so that the drag goes
-     * through the same `applyDelta` the wheel and the arrow keys do. Carrying
-     * the modifier map over rather than resolving it here is what keeps `step`
-     * out of the pipeline for a modifier entry — naming one is a request to move
-     * off the grid.
-     */
-    const dragOptions = useMemo(
-      () =>
-        mapModifier(dragSensitivity, (factor): InputEventOption => [
-          'raw',
-          step * factor,
-        ]),
-      [dragSensitivity, step],
-    )
+    // Only attached while it can do something: `createDrag` puts
+    // `touch-action: none` on the element, and a stepper that cannot be
+    // dragged has no reason to stop the page scrolling under a finger.
+    const enabled = drag !== null && !disabled && !readOnly
 
-    /**
-     * Set once the drag has actually moved the value, so that the press-and-hold
-     * repeat of a stepper stands down and leaves the value to the drag. A ref,
-     * because it is read from inside the repeat rather than rendered.
-     */
-    const draggingRef = useRef(false)
-    /**
-     * Where the drag started, taken on the first move rather than on pointer
-     * down: the steppers act on pointer down, so by then the value may already
-     * have been nudged once, and the drag should carry on from there.
-     */
-    const originRef = useRef<{ y: number; value: number } | null>(null)
-    /**
-     * Which modifier the drag is currently counting at, and where the previous
-     * event was — a key produces no pointer event of its own, so a change is
-     * only seen on the next move and has to be dated back to the one before it.
-     */
-    const factorRef = useRef<number>(1)
-    const previousYRef = useRef(0)
+    // See useDrag for why the node is held in state rather than a ref.
+    const [node, setNode] = useState<HTMLDivElement | null>(null)
+    const instanceRef = useRef<StepperDragInstance | null>(null)
+    const latest = useRef({ value, changeValue })
+    const options = {
+      range: rawRange,
+      pixels: drag ?? 1,
+      sensitivity: dragSensitivity,
+      pointerLock,
+      cursor: dragCursor,
+    }
+    const optionsRef = useRef(options)
 
-    const dragRefCallback = useDrag<HTMLDivElement>({
-      threshold: 1,
-      cursor: inactive ? undefined : 'ns-resize',
-      pointerLock: inactive ? false : pointerLock,
-      onDragStart: (state) => {
-        originRef.current = null
-        draggingRef.current = false
-        factorRef.current = selectModifier(dragSensitivity, state.event).value
-      },
-      onDrag: (_x, y, _dx, _dy, state) => {
-        if (inactive || drag === null) return
-        if (!originRef.current) {
-          originRef.current = { y, value }
-          previousYRef.current = y
-          return
-        }
+    // Runs after every render.
+    useEffect(() => {
+      latest.current = { value, changeValue }
+      optionsRef.current = options
+      instanceRef.current?.update(options)
+    })
 
-        // Pressing or releasing the key mid-drag must not move the value, so the
-        // travel so far is folded into the origin and measuring starts again
-        // from the previous event: that event's own distance belongs to the new
-        // sensitivity.
-        const factor = selectModifier(dragSensitivity, state.event).value
-        if (factor !== factorRef.current) {
-          originRef.current = { y: previousYRef.current, value }
-          factorRef.current = factor
-        }
-        previousYRef.current = y
+    useEffect(() => {
+      if (!node || !enabled) return
+      const instance = createStepperDrag(node, {
+        ...optionsRef.current,
+        getValue: () => latest.current.value,
+        onChange: (next) => latest.current.changeValue(next),
+      })
+      instanceRef.current = instance
+      return () => {
+        instanceRef.current = null
+        instance.destroy()
+      }
+    }, [node, enabled])
 
-        // Dragging up raises the value, as on a knob.
-        const steps = Math.round(-(y - originRef.current.y) / drag)
-        if (steps === 0) return
-        draggingRef.current = true
-        // The same pipeline the wheel and the arrow keys use. Counting from where
-        // the drag started keeps it from accumulating a rounding error.
-        changeValue(
-          applyDelta(
-            originRef.current.value,
-            steps,
-            dragOptions,
-            rawRange,
-            state.event,
-          ),
-        )
-      },
-      onDragEnd: () => {
-        draggingRef.current = false
-      },
-    })
+    const gesture = useNumberInputGesture()
+    const composedRef = useComposedRefs<HTMLDivElement>(forwardedRef, setNode)
 
-    const composedRef = useComposedRefs<HTMLDivElement>(
-      forwardedRef,
-      drag !== null && !inactive ? dragRefCallback : undefined,
+    const context = useMemo(
+      () => ({ moved: () => instanceRef.current?.moved() ?? false }),
+      [],
     )
 
-    const context = useMemo(() => ({ draggingRef }), [])
-
     return (
       <StepperProvider value={context}>
-        <div ref={composedRef} className={className} style={style} {...props}>
+        <div
+          ref={composedRef}
+          className={className}
+          style={style}
+          onPointerDown={(event) => {
+            // A drag on the stepper is a press like any other: held from here
+            // until the pointer is released.
+            if (enabled) gesture?.press()
+            onPointerDown?.(event)
+          }}
+          {...props}
+        >
           {children}
         </div>
       </StepperProvider>