@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/Knob/index.tsx

@@ -1,89 +1,205 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
+  ReactNode,
   useCallback,
   useImperativeHandle,
+  useMemo,
   useRef,
-  useState,
 } from 'react'
 
+import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
-  clamp,
-  InputEventOption,
-  normalizeValue,
-  rawValue,
-  stepValue,
+  applyDelta,
+  type InputEventOption,
+  type ModifierValue,
+  selectModifier,
+  linearScale,
+  type Scale,
+  type ValueRange,
 } from '@tremolo-ui/functions'
 
-import { useDrag } from '../../hooks/useDrag'
+import { useComposedRefs } from '../../compose-refs'
+import { useCheckSteps } from '../../hooks/_internal/useCheckSteps'
+import { useDragValue } from '../../hooks/useDragValue'
 import { useWheel } from '../../hooks/useWheel'
-import { addUserSelectNone, Cursor, removeUserSelectNone } from '../_util'
+import {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+} from '../../input-event'
+import { cssLength } from '../_util/css-length'
 
 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'
 
 const defaultExternalStyles: KnobProps['externalStyles'] = {
-  userSelectNone: true,
   cursor: 'grabbing',
 }
 
 export interface KnobProps {
-  // required
+  /** The current value. The knob shows only this, so update it from `onChange`. */
   value: number
+  /** The value with the knob turned all the way down. */
   min: number
+  /** The value with the knob turned all the way up. */
   max: number
 
-  // optional
+  /**
+   * Granularity of the value. A drag, the wheel and the arrow keys snap it to
+   * multiples of `step`.
+   *
+   * @default 1
+   */
   step?: number
-  skew?: number // | SkewFunction // TODO
   /**
-   * value set when double-clicking
-   * restriction: enableDoubleClickDefault = true
+   * 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
+  /**
+   * The value a double click restores, while `enableDoubleClickDefault` is on.
    * @default min
-   * @see enableDoubleClickDefault
    */
   defaultValue?: number
 
   /**
-   * Value to be used as the starting point of the line when drawing.
+   * Where the active arc starts. Put it at the centre of a bipolar control,
+   * such as a pan knob, so that the arc grows from there either way.
    * @default min
    */
   startValue?: number
 
-  /** width and height */
+  /**
+   * Width and height of the knob. Sets `--knob-size`; the size the theme
+   * gives it stands when this is omitted.
+   */
   size?: number | string
 
   /**
-   * Global style to apply when dragged
-   * @default defaultExternalStyles
+   * 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' }
    */
   externalStyles?: {
-    userSelectNone?: boolean
-    cursor?: Cursor
+    cursor?: CSSProperties['cursor']
   }
   /**
-   * wheel control option
-   * If null, no event will be triggered
+   * 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.
+   *
+   * `['raw', n]` moves the value by `n`, and `['normalized', n]` by `n` of the
+   * range between `min` and `max`. The result is snapped to `step`, except for
+   * an amount set on a modifier key (`{ default: …, shift: … }`). `null` turns
+   * the wheel off.
+   *
+   * @default ['raw', 1]
    */
-  wheel?: InputEventOption | null
+  wheel?: ModifierValue<InputEventOption> | null
   /**
-   * keyboard control option
-   * If null, no event will be triggered
+   * How much a drag moves the value, per modifier key.
+   *
+   * `1` is the normal travel of 100px for the whole range; `0.1` makes the
+   * same movement cover a tenth of it. Shift is bound to `0.1` by default, to
+   * match what it does on the arrow keys.
+   *
+   * Pressing or releasing the key mid-drag does not disturb the value: the
+   * travel so far is kept and the new sensitivity applies from there. It takes
+   * effect on the next movement, since a key on its own produces no pointer
+   * event.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  dragSensitivity?: ModifierValue<number>
+
+  /**
+   * Hide the cursor while dragging and read the pointer movement directly,
+   * rather than letting it wander off across the screen.
+   *
+   * A knob does not care where the pointer is, only how far it moved, and
+   * letting it wander costs twice: the cursor ends up far from the knob it is
+   * holding, and **the drag stops at the edge of the screen**, where the
+   * operating system pins the pointer and the coordinates stop changing. A
+   * `dragSensitivity` below 1 reaches that edge quickly.
+   *
+   * Off by default because it is not free: the browser shows its own notice,
+   * Esc takes the lock back, and the request needs a user gesture and can be
+   * refused. A refused request is not an error — the drag simply carries on as
+   * an ordinary one.
+   *
+   * @default false
+   */
+  pointerLock?: boolean
+
+  /**
+   * How much one arrow key press moves the value.
+   *
+   * `['raw', n]` moves the value by `n`, and `['normalized', n]` by `n` of the
+   * range between `min` and `max`. The result is snapped to `step`, except for
+   * an amount set on a modifier key, which is what lets shift move off the
+   * grid. `null` turns the arrow keys off.
+   *
+   * The default moves by 1, and by 0.1 with shift. With a `step` above 1, raise
+   * the amount to match: 1 would round straight back to where it started, and
+   * a development build warns about it.
+   *
+   * @default { default: ['raw', 1], shift: ['raw', 0.1] }
+   */
+  keyboard?: ModifierValue<InputEventOption> | null
+  /**
+   * Restore `defaultValue` on a double click.
+   * @default true
    */
-  keyboard?: InputEventOption | null
   enableDoubleClickDefault?: boolean
 
+  /**
+   * Make the knob unchangeable and remove it from the tab order.
+   * The parts carry `data-disabled` while it is set.
+   */
   disabled?: boolean
+  /**
+   * Make the knob unchangeable while leaving it focusable.
+   * The parts carry `data-readonly` while it is set.
+   */
   readonly?: boolean
 
-  /** angle range [degree] */
+  /**
+   * How far the knob turns from `min` to `max`, in degrees, centred on the
+   * top.
+   * @default 270
+   */
   angleRange?: number
 
+  /**
+   * Called with the new value when a drag, the wheel, an arrow key or a double
+   * click moves it.
+   */
   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,20 +209,28 @@ 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 = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
   (
     {
       value,
       min,
       max,
       step = 1,
-      skew = 1,
+      scale = linearScale,
       defaultValue = min,
       startValue = min,
       size,
       externalStyles: _externalStyles,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      pointerLock = false,
       enableDoubleClickDefault = true,
       disabled = false,
       readonly = false,
@@ -122,118 +246,114 @@ 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 }
+    const inactive = disabled || readonly
 
     // --- 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 range: ValueRange = useMemo(
+      () => ({ min, max, step, scale }),
+      [min, max, step, scale],
     )
 
-    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],
-    )
+    useCheckSteps({ component: 'Knob', range, keyboard, wheel })
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLOrSVGElement>) => {
-        if (!keyboard || !onChange || readonly) return
+        if (!keyboard || !onChange || inactive) return
         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, event))
         }
       },
-      [keyboard, onChange, readonly, updateValueByEvent],
+      [keyboard, onChange, inactive, value, range],
     )
 
     // --- hooks ---
-    const dragRefCallback = useDrag<HTMLElement | SVGElement>({
-      cursor: readonly ? undefined : externalStyles.cursor,
-      onDrag: onDrag,
-      onDragStart: () => {
-        setDragging(true)
-        valueRef.current = normalizeValue(value, min, max, skew)
-        if (externalStyles.userSelectNone) addUserSelectNone()
-      },
-      onDragEnd: () => {
-        setDragging(false)
-        if (externalStyles.userSelectNone) removeUserSelectNone()
+    // 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],
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
+      threshold: 1,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      pointerLock: inactive ? false : pointerLock,
+      shouldStart: () => !inactive,
+      onChange: (v) => {
+        if (inactive) return
+        onChange?.(v[1])
       },
     })
 
     const wheelRefCallback = useWheel<HTMLElement>((event) => {
-      if (!wheel || readonly) return
+      if (!wheel || inactive) return
       event.preventDefault()
-      if (!onChange || event.deltaY == 0) return
-      const x = Math.sign(event.deltaY) * -wheel[1]
-      onChange(updateValueByEvent(wheel[0], x))
-    })
+      if (!onChange || event.deltaY === 0) return
+      onChange(applyDelta(value, -Math.sign(event.deltaY), 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>(
+      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 {
         focus() {
-          elmRef.current?.focus()
+          if (!disabled) elmRef.current?.focus()
         },
         blur() {
           elmRef.current?.blur()
         },
       }
-    }, [])
+    }, [disabled])
 
     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)
-          }}
-          className={clsx('tremolo-knob', className)}
-          tabIndex={0}
+          ref={rootRefCallback}
+          className={className}
+          tabIndex={disabled ? -1 : 0}
           role="slider"
           aria-valuenow={value}
           aria-valuemin={min}
           aria-valuemax={max}
           aria-disabled={disabled}
           aria-readonly={readonly}
-          data-dragging={dragging}
-          style={{
-            width: size,
-            height: size,
-            ...style,
-          }}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
+          data-dragging={dragging ? '' : undefined}
+          style={
+            {
+              '--knob-size': cssLength(size),
+              ...style,
+            } as CSSProperties
+          }
           onPointerDown={onPointerDown}
           onDoubleClick={(event) => {
-            if (enableDoubleClickDefault && onChange) {
+            if (!inactive && enableDoubleClickDefault && onChange) {
               onChange(defaultValue)
             }
             onDoubleClick?.(event)
@@ -244,7 +364,7 @@ const Root = forwardRef<KnobMethods, Props>(
           }}
           {...props}
         >
-          {children || <SVGRoot />}
+          {children}
         </div>
       </KnobProvider>
     )
@@ -262,4 +382,6 @@ export const Knob = {
   Thumb,
 }
 
-export { useKnobContext } from './context'
+export { useKnobContext, type KnobContextValue } from './context'
+export { type KnobSVGRootProps } from './SVGRoot'
+export { type KnobThumbProps } from './Thumb'

package/src/components/NumberInput/DecrementStepper.tsx

@@ -1,57 +1,28 @@
-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)
+// An interface rather than an alias; see `NumberInputIncrementStepperProps`.
+export interface NumberInputDecrementStepperProps extends StepperButtonProps {}
 
+/** Lowers the value by one `step`, repeating while held. */
+export function DecrementStepper(
+  props: NumberInputDecrementStepperProps &
+    Omit<
+      ComponentPropsWithoutRef<'div'>,
+      keyof NumberInputDecrementStepperProps
+    >,
+) {
   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,29 @@
-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)
+// An interface rather than an alias, so that typedoc lists the props: the
+// shared `StepperButtonProps` is not exported for it to follow.
+export interface NumberInputIncrementStepperProps extends StepperButtonProps {}
 
+/** Raises the value by one `step`, repeating while held. */
+export function IncrementStepper(
+  props: NumberInputIncrementStepperProps &
+    Omit<
+      ComponentPropsWithoutRef<'div'>,
+      keyof NumberInputIncrementStepperProps
+    >,
+) {
   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>
+    />
   )
 }