@tremolo-ui/react 0.4.0 → 0.5.0

package/src/components/Knob/index.tsx

@@ -2,26 +2,29 @@ import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
   forwardRef,
+  ReactNode,
   useCallback,
   useImperativeHandle,
+  useMemo,
   useRef,
-  useState,
 } from 'react'
 
+import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
-  clamp,
+  applyDelta,
   InputEventOption,
-  normalizeValue,
-  rawValue,
-  stepValue,
+  linearScale,
+  type Scale,
+  type ValueRange,
 } from '@tremolo-ui/functions'
 
-import { useDrag } from '../../hooks/useDrag'
+import { useDragValue } from '../../hooks/useDragValue'
 import { useWheel } from '../../hooks/useWheel'
 import { addUserSelectNone, Cursor, removeUserSelectNone } from '../_util'
+import { useComposedRefs } from '../_util/composeRefs'
 
 import { ActiveLine } from './ActiveLine'
-import { KnobProvider } from './context'
+import { calcAngles, KnobProvider } from './context'
 import { InactiveLine } from './InactiveLine'
 import { SVGRoot } from './SVGRoot'
 import { Thumb } from './Thumb'
@@ -39,7 +42,16 @@ export interface KnobProps {
 
   // optional
   step?: number
-  skew?: number // | SkewFunction // TODO
+  /**
+   * How the value is distributed across the travel.
+   *
+   * Pick one of the scales from `@tremolo-ui/functions`: `linearScale`,
+   * `exponentialScale`, `curveScale(n)`, `symmetricSkewScale(n)`, or
+   * `skewScale(n)` for a value that has to match a JUCE parameter.
+   *
+   * @default linearScale
+   */
+  scale?: Scale
   /**
    * value set when double-clicking
    * restriction: enableDoubleClickDefault = true
@@ -55,6 +67,10 @@ export interface KnobProps {
   startValue?: number
 
   /** width and height */
+  /**
+   * Width and height of the knob.
+   * Defaults to the `--knob-size` CSS variable (50px).
+   */
   size?: number | string
 
   /**
@@ -84,6 +100,21 @@ export interface KnobProps {
   angleRange?: number
 
   onChange?: (value: number) => void
+
+  /**
+   * The knob renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <Knob.Root value={value} min={0} max={100} onChange={setValue}>
+   *   <Knob.SVGRoot>
+   *     <Knob.InactiveLine />
+   *     <Knob.ActiveLine />
+   *     <Knob.Thumb />
+   *   </Knob.SVGRoot>
+   * </Knob.Root>
+   */
+  children: ReactNode
 }
 
 export interface KnobMethods {
@@ -93,14 +124,20 @@ export interface KnobMethods {
 
 type Props = KnobProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KnobProps>
 
-const Root = forwardRef<KnobMethods, Props>(
+/**
+ * The wheel only acts while the focus is inside, so that scrolling a page past
+ * the control does not change its value.
+ */
+const WHEEL_OPTIONS = { requireFocus: true }
+
+export const Root = forwardRef<KnobMethods, Props>(
   (
     {
       value,
       min,
       max,
       step = 1,
-      skew = 1,
+      scale = linearScale,
       defaultValue = min,
       startValue = min,
       size,
@@ -122,35 +159,14 @@ const Root = forwardRef<KnobMethods, Props>(
     }: Props,
     forwardedRef,
   ) => {
-    const [dragging, setDragging] = useState(false)
-    const valueRef = useRef(0)
     const elmRef = useRef<HTMLElement | SVGElement>(null)
 
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
 
     // --- internal functions ---
-    const onDrag = useCallback(
-      (_x: number, y: number) => {
-        if (!onChange || readonly) return
-        const v = rawValue(valueRef.current - y / 100, min, max, skew)
-        const clamped = clamp(stepValue(v, step), min, max)
-        onChange(clamped)
-      },
-      [max, min, onChange, readonly, skew, step],
-    )
-
-    const updateValueByEvent = useCallback(
-      (eventType: InputEventOption[0], x: number) => {
-        let newValue
-        if (eventType == 'normalized') {
-          const n = normalizeValue(value, min, max, skew)
-          newValue = rawValue(n + x, min, max, skew)
-        } else {
-          newValue = value + x
-        }
-        return clamp(stepValue(newValue, step), min, max)
-      },
-      [max, min, skew, step, value],
+    const range: ValueRange = useMemo(
+      () => ({ min, max, step, scale }),
+      [min, max, step, scale],
     )
 
     const handleKeyDown = useCallback(
@@ -159,25 +175,38 @@ const Root = forwardRef<KnobMethods, Props>(
         const key = event.key
         if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
           event.preventDefault()
-          const x =
-            key == 'ArrowRight' || key == 'ArrowUp' ? keyboard[1] : -keyboard[1]
-          onChange(updateValueByEvent(keyboard[0], x))
+          const direction = key == 'ArrowRight' || key == 'ArrowUp' ? 1 : -1
+          onChange(applyDelta(value, direction, keyboard, range))
         }
       },
-      [keyboard, onChange, readonly, updateValueByEvent],
+      [keyboard, onChange, readonly, value, range],
     )
 
     // --- hooks ---
-    const dragRefCallback = useDrag<HTMLElement | SVGElement>({
+    // The knob has no travel of its own: the value moves away from where it
+    // stood when the drag started, 100px of movement spanning the whole range.
+    // Only the vertical axis carries a value, reversed so that dragging up
+    // raises it.
+    const axis = useMemo(
+      (): XY<AxisOptions> => [range, { ...range, reverse: true }],
+      [range],
+    )
+
+    const { refCallback: dragRefCallback, dragging } = useDragValue<
+      HTMLElement | SVGElement
+    >({
+      axis,
+      getValue: () => [value, value],
+      threshold: 1,
       cursor: readonly ? undefined : externalStyles.cursor,
-      onDrag: onDrag,
+      onChange: (v) => {
+        if (readonly) return
+        onChange?.(v[1])
+      },
       onDragStart: () => {
-        setDragging(true)
-        valueRef.current = normalizeValue(value, min, max, skew)
         if (externalStyles.userSelectNone) addUserSelectNone()
       },
       onDragEnd: () => {
-        setDragging(false)
         if (externalStyles.userSelectNone) removeUserSelectNone()
       },
     })
@@ -186,9 +215,21 @@ const Root = forwardRef<KnobMethods, Props>(
       if (!wheel || readonly) return
       event.preventDefault()
       if (!onChange || event.deltaY == 0) return
-      const x = Math.sign(event.deltaY) * -wheel[1]
-      onChange(updateValueByEvent(wheel[0], x))
-    })
+      onChange(applyDelta(value, -Math.sign(event.deltaY), wheel, range))
+    }, 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>(
+      elmRef,
+      dragRefCallback,
+      wheelRefCallback,
+    )
+
+    const context = useMemo(() => {
+      const config = { value, min, max, step, scale, startValue, angleRange }
+      return { ...config, ...calcAngles(config) }
+    }, [value, min, max, step, scale, startValue, angleRange])
 
     useImperativeHandle(forwardedRef, () => {
       return {
@@ -202,21 +243,9 @@ const Root = forwardRef<KnobMethods, Props>(
     }, [])
 
     return (
-      <KnobProvider
-        value={value}
-        min={min}
-        max={max}
-        step={step}
-        skew={skew}
-        startValue={startValue}
-        angleRange={angleRange}
-      >
+      <KnobProvider value={context}>
         <div
-          ref={(elm) => {
-            elmRef.current = elm
-            wheelRefCallback(elm)
-            dragRefCallback(elm)
-          }}
+          ref={rootRefCallback}
           className={clsx('tremolo-knob', className)}
           tabIndex={0}
           role="slider"
@@ -244,7 +273,7 @@ const Root = forwardRef<KnobMethods, Props>(
           }}
           {...props}
         >
-          {children || <SVGRoot />}
+          {children}
         </div>
       </KnobProvider>
     )

package/src/components/NumberInput/DecrementStepper.tsx

@@ -1,57 +1,24 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, ReactNode } from 'react'
+import { ComponentPropsWithoutRef } from 'react'
 
-import { useLongPress } from '../../hooks/useLongPress'
+import {
+  StepperArrow,
+  StepperButton,
+  StepperButtonProps,
+} from './stepperButton'
 
-import { useNumberInputContext } from './context'
-
-export interface DecrementStepperProps {
-  size?: number
-  children?: ReactNode
-}
-
-export function DecrementStepper({
-  size = 12,
-  children,
-  className,
-  ...props
-}: DecrementStepperProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof DecrementStepperProps>) {
-  const min = useNumberInputContext((s) => s.min)
-  const valueAsNumber = useNumberInputContext((s) => s.valueAsNumber)
-  const readonly = useNumberInputContext((s) => s.readonly)
-  const keepWithinRange = useNumberInputContext((s) => s.keepWithinRange)
-  const decrement = useNumberInputContext((s) => s.decrement)
-
-  const press = useLongPress(decrement)
+export type DecrementStepperProps = StepperButtonProps
 
+/** Lowers the value by one `step`, repeating while held. */
+export function DecrementStepper(
+  props: DecrementStepperProps &
+    Omit<ComponentPropsWithoutRef<'div'>, keyof DecrementStepperProps>,
+) {
   return (
-    // eslint-disable-next-line jsx-a11y/role-supports-aria-props
-    <div
-      className={clsx('tremolo-number-input-decrement-stepper', className)}
-      role="button"
-      tabIndex={-1}
-      aria-disabled={
-        keepWithinRange && valueAsNumber <= (min ?? Number.MIN_SAFE_INTEGER)
-      }
-      aria-readonly={readonly}
-      onPointerDown={press}
+    <StepperButton
+      direction={-1}
+      variant="decrement"
+      icon={<StepperArrow up={false} />}
       {...props}
-    >
-      {children || (
-        <svg
-          width={size}
-          height={size}
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-        >
-          <polyline points="6 9 12 15 18 9" />
-        </svg>
-      )}
-    </div>
+    />
   )
 }

package/src/components/NumberInput/IncrementStepper.tsx

@@ -1,57 +1,24 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, ReactNode } from 'react'
+import { ComponentPropsWithoutRef } from 'react'
 
-import { useLongPress } from '../../hooks/useLongPress'
+import {
+  StepperArrow,
+  StepperButton,
+  StepperButtonProps,
+} from './stepperButton'
 
-import { useNumberInputContext } from './context'
-
-export interface IncrementStepperProps {
-  size?: number
-  children?: ReactNode
-}
-
-export function IncrementStepper({
-  size = 12,
-  children,
-  className,
-  ...props
-}: IncrementStepperProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof IncrementStepperProps>) {
-  const max = useNumberInputContext((s) => s.max)
-  const valueAsNumber = useNumberInputContext((s) => s.valueAsNumber)
-  const readonly = useNumberInputContext((s) => s.readonly)
-  const keepWithinRange = useNumberInputContext((s) => s.keepWithinRange)
-  const increment = useNumberInputContext((s) => s.increment)
-
-  const press = useLongPress(increment)
+export type IncrementStepperProps = StepperButtonProps
 
+/** Raises the value by one `step`, repeating while held. */
+export function IncrementStepper(
+  props: IncrementStepperProps &
+    Omit<ComponentPropsWithoutRef<'div'>, keyof IncrementStepperProps>,
+) {
   return (
-    // eslint-disable-next-line jsx-a11y/role-supports-aria-props
-    <div
-      className={clsx('tremolo-number-input-increment-stepper', className)}
-      role="button"
-      tabIndex={-1}
-      aria-disabled={
-        keepWithinRange && valueAsNumber >= (max ?? Number.MAX_SAFE_INTEGER)
-      }
-      aria-readonly={readonly}
-      onPointerDown={press}
+    <StepperButton
+      direction={1}
+      variant="increment"
+      icon={<StepperArrow up />}
       {...props}
-    >
-      {children || (
-        <svg
-          width={size}
-          height={size}
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="2"
-          strokeLinecap="round"
-          strokeLinejoin="round"
-        >
-          <polyline points="18 15 12 9 6 15" />
-        </svg>
-      )}
-    </div>
+    />
   )
 }

package/src/components/NumberInput/InputField.tsx

@@ -0,0 +1,123 @@
+import clsx from 'clsx'
+import { ComponentPropsWithoutRef, CSSProperties, Ref } from 'react'
+
+import { useComposedRefs } from '../_util/composeRefs'
+
+import { useNumberInputContext } from './context'
+
+export interface NumberInputFieldProps {
+  /**
+   * Select the text when the input takes focus. `'number'` selects the leading
+   * number, leaving whatever the format appended to it.
+   * @default 'none'
+   */
+  selectOnFocus?: 'all' | 'number' | 'none'
+  /**
+   * Commit and leave the input when Enter is pressed. Enter commits either way.
+   * @default true
+   */
+  blurOnEnter?: boolean
+
+  className?: string
+  style?: CSSProperties
+  ref?: Ref<HTMLInputElement>
+}
+
+/** The leading number of the displayed text, whatever the format put around it. */
+const NUMBER_PREFIX = /^\s*-?[\d.,]*/
+
+/**
+ * The text field of a `NumberInput`, and the only place the value can be typed.
+ *
+ * While the user types, their own text stands rather than `format(value)`, so
+ * that a half-finished entry is not rewritten under the caret.
+ */
+export function InputField({
+  selectOnFocus = 'none',
+  blurOnEnter = true,
+  className,
+  style,
+  ref,
+  onFocus,
+  onBlur,
+  onKeyDown,
+  ...props
+}: NumberInputFieldProps &
+  Omit<
+    ComponentPropsWithoutRef<'input'>,
+    keyof NumberInputFieldProps | 'type' | 'value' | 'defaultValue'
+  >) {
+  const {
+    value,
+    min,
+    max,
+    step,
+    disabled,
+    readonly,
+    keyboard,
+    text,
+    outOfRange,
+    setDraft,
+    commitDraft,
+    nudge,
+    inputRef,
+  } = useNumberInputContext()
+
+  const composedRef = useComposedRefs<HTMLInputElement>(ref, inputRef)
+
+  return (
+    <input
+      ref={composedRef}
+      className={clsx('tremolo-number-input-field', className)}
+      // Not type="number": that brings native spinners and a value the browser
+      // parses itself, neither of which survives a unit suffix.
+      type="text"
+      inputMode="decimal"
+      role="spinbutton"
+      value={text}
+      readOnly={readonly}
+      aria-disabled={disabled}
+      aria-readonly={readonly}
+      aria-valuenow={value}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuetext={text}
+      step={step}
+      data-out-of-range={outOfRange}
+      style={style}
+      onChange={(event) => setDraft(event.currentTarget.value)}
+      onFocus={(event) => {
+        const input = event.currentTarget
+        if (selectOnFocus == 'all') {
+          input.setSelectionRange(0, input.value.length)
+        } else if (selectOnFocus == 'number') {
+          input.setSelectionRange(
+            0,
+            input.value.match(NUMBER_PREFIX)?.[0].length ?? 0,
+          )
+        }
+        onFocus?.(event)
+      }}
+      onBlur={(event) => {
+        commitDraft()
+        onBlur?.(event)
+      }}
+      onKeyDown={(event) => {
+        const key = event.key
+        if (key == 'Enter') {
+          commitDraft()
+          if (blurOnEnter) event.currentTarget.blur()
+        } else if (
+          keyboard &&
+          !readonly &&
+          (key == 'ArrowUp' || key == 'ArrowDown')
+        ) {
+          event.preventDefault()
+          nudge(key == 'ArrowUp' ? 1 : -1, keyboard)
+        }
+        onKeyDown?.(event)
+      }}
+      {...props}
+    />
+  )
+}

package/src/components/NumberInput/Stepper.tsx

@@ -1,25 +1,103 @@
 import clsx from 'clsx'
-import { ComponentPropsWithoutRef, ReactNode } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  ReactNode,
+  Ref,
+  useMemo,
+  useRef,
+} from 'react'
+
+import { applyDelta } from '@tremolo-ui/functions'
+
+import { useDrag } from '../../hooks/useDrag'
+import { useComposedRefs } from '../_util/composeRefs'
+
+import { StepperProvider, useNumberInputContext } from './context'
 
 export interface StepperProps {
-  /** Display only when hovering. */
-  dynamic?: boolean
+  className?: string
+  style?: CSSProperties
+  /** `<NumberInput.IncrementStepper />` and `<NumberInput.DecrementStepper />` go here. */
   children?: ReactNode
+  ref?: Ref<HTMLDivElement>
 }
 
+/**
+ * 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.
+ *
+ * The drag lives here rather than on `InputField` because `createDrag` turns
+ * off text selection on whatever element it is attached to.
+ */
 export function Stepper({
-  dynamic = true,
-  children,
   className,
+  style,
+  children,
+  ref,
   ...props
 }: StepperProps & Omit<ComponentPropsWithoutRef<'div'>, keyof StepperProps>) {
+  const { value, step, readonly, drag, range, changeValue } =
+    useNumberInputContext()
+
+  /**
+   * 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)
+
+  const dragRefCallback = useDrag<HTMLDivElement>({
+    threshold: 1,
+    cursor: readonly ? undefined : 'ns-resize',
+    onDragStart: () => {
+      originRef.current = null
+      draggingRef.current = false
+    },
+    onDrag: (_x, y) => {
+      if (readonly || drag == null) return
+      if (!originRef.current) {
+        originRef.current = { y, value }
+        return
+      }
+      // 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, ['raw', step], range),
+      )
+    },
+    onDragEnd: () => {
+      draggingRef.current = false
+    },
+  })
+
+  const composedRef = useComposedRefs<HTMLDivElement>(
+    ref,
+    drag != null && !readonly ? dragRefCallback : undefined,
+  )
+
+  const context = useMemo(() => ({ draggingRef }), [])
+
   return (
-    <div
-      className={clsx('tremolo-number-input-stepper', className)}
-      data-dynamic={dynamic}
-      {...props}
-    >
-      {children}
-    </div>
+    <StepperProvider value={context}>
+      <div
+        ref={composedRef}
+        className={clsx('tremolo-number-input-stepper', className)}
+        style={style}
+        {...props}
+      >
+        {children}
+      </div>
+    </StepperProvider>
   )
 }