@tremolo-ui/react 0.4.0 → 0.5.0

package/src/components/XYPad/index.css

@@ -1,6 +1,16 @@
 .tremolo-xy-pad {
+  /* Half the thumb size. The thumb overhangs the edges of the area, so the
+     pad reserves room for it. Override this when using a different size. */
+  --thumb-size: 22px;
+
   display: inline-block;
+  margin: calc(var(--thumb-size) / 2);
   cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+
+  &[aria-readonly='true'] {
+    cursor: not-allowed;
+  }
 }
 
 .tremolo-xy-pad-area {
@@ -19,6 +29,8 @@
 .tremolo-xy-pad-thumb {
   --color: oklch(59.5% 0.17548 266.373);
 
+  width: var(--thumb-size);
+  height: var(--thumb-size);
   border-radius: 50%;
   outline: none;
   background-color: var(--color);

package/src/components/XYPad/index.tsx

@@ -1,8 +1,8 @@
 import clsx from 'clsx'
-import React, {
+import {
   ComponentPropsWithoutRef,
   forwardRef,
-  ReactElement,
+  ReactNode,
   Ref,
   useCallback,
   useImperativeHandle,
@@ -10,31 +10,23 @@ import React, {
   useRef,
 } from 'react'
 
+import type { AxisOptions } from '@tremolo-ui/dom'
 import {
-  clamp,
-  normalizeValue,
-  rawValue,
-  stepValue,
+  applyDelta,
+  linearScale,
   toFixed,
   InputEventOption,
-  styleHelper,
+  type Scale,
 } from '@tremolo-ui/functions'
 
-import { useDragWithElement } from '../../hooks/useDragWithElement'
+import { useDragValue } from '../../hooks/useDragValue'
 import { useWheel } from '../../hooks/useWheel'
 import { addUserSelectNone, Cursor, removeUserSelectNone } from '../_util'
-import { composeRefs } from '../_util/composeRefs'
-
-import { Area, XYPadAreaProps } from './Area'
-import { Thumb, XYPadThumbMethods, XYPadThumbProps } from './Thumb'
+import { useComposedRefs } from '../_util/composeRefs'
 
-const defaultValueOptions = {
-  skew: 1,
-  step: 1,
-  reverse: false,
-  wheel: ['raw', 1] as InputEventOption,
-  keyboard: ['raw', 1] as InputEventOption,
-}
+import { Area } from './Area'
+import { toXY, XY, XYInput, XYPadProvider } from './context'
+import { Thumb, XYPadThumbMethods } from './Thumb'
 
 const defaultExternalStyles: XYPadProps['externalStyles'] = {
   userSelectNone: true,
@@ -43,30 +35,38 @@ const defaultExternalStyles: XYPadProps['externalStyles'] = {
 
 /**
  * Two-dimensional slider component.
+ *
+ * The per-axis settings mirror `Slider`, given as `[x, y]` tuples. A plain
+ * value applies to both axes.
  */
-export interface ValueOptions {
-  // required
-  value: number
-  min: number
-  max: number
+export interface XYPadProps {
+  value: XY<number>
+  min: XYInput<number>
+  max: XYInput<number>
+
+  step?: XYInput<number>
+  /**
+   * How the value of each axis 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?: XYInput<Scale>
+  reverse?: XYInput<boolean>
 
-  // optional
-  step?: number
-  skew?: number
-  reverse?: boolean
   /**
-   * wheel control option
+   * wheel control option. Shift selects the x axis.
+   * If null, no event will be triggered
    */
   wheel?: InputEventOption | null
   /**
    * keyboard control option
+   * If null, no event will be triggered
    */
   keyboard?: InputEventOption | null
-}
-
-export interface XYPadProps {
-  x: ValueOptions
-  y: ValueOptions
 
   externalStyles?: {
     userSelectNone?: boolean
@@ -76,11 +76,22 @@ export interface XYPadProps {
   disabled?: boolean
   readonly?: boolean
 
-  onChange?: (valueX: number, valueY: number) => void
-  onDragStart?: (valueX: number, valueY: number) => void
-  onDragEnd?: (valueX: number, valueY: number) => void
-  /** \<XYPadThumb /> | \<XYPadArea /> */
-  children?: ReactElement | ReactElement[]
+  onChange?: (value: XY<number>) => void
+  onDragStart?: (value: XY<number>) => void
+  onDragEnd?: (value: XY<number>) => void
+
+  /**
+   * The pad renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <XYPad.Root value={[x, y]} min={0} max={100} onChange={setValue}>
+   *   <XYPad.Area>
+   *     <XYPad.Thumb />
+   *   </XYPad.Area>
+   * </XYPad.Root>
+   */
+  children: ReactNode
 }
 
 export interface XYPadMethods {
@@ -92,11 +103,23 @@ export interface XYPadMethods {
 type Props = XYPadProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadProps>
 
+/**
+ * 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<XYPadMethods, Props>(
   (
     {
-      x: _x,
-      y: _y,
+      value,
+      min: _min,
+      max: _max,
+      step: _step = 1,
+      scale: _scale = linearScale,
+      reverse: _reverse = false,
+      wheel = ['raw', 1],
+      keyboard = ['raw', 1],
       className,
       style,
       externalStyles: _externalStyles,
@@ -114,178 +137,133 @@ export const Root = forwardRef<XYPadMethods, Props>(
     }: Props,
     forwardedRef,
   ) => {
-    const x = useMemo(() => {
-      return { ...defaultValueOptions, ..._x }
-    }, [_x])
-    const y = useMemo(() => {
-      return { ...defaultValueOptions, ..._y }
-    }, [_y])
-
     // -- state and ref ---
     const rootRef = useRef<HTMLDivElement>(null)
-    const areaElementRef = useRef<HTMLDivElement>(null)
+    const areaRef = useRef<HTMLDivElement>(null)
     const thumbRef = useRef<XYPadThumbMethods>(null)
 
     // --- interpret props ---
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
 
-    const nx = normalizeValue(x.value, x.min, x.max, x.skew)
-    const ny = normalizeValue(y.value, y.min, y.max, y.skew)
-    const percentX = toFixed((x.reverse ? 1 - nx : nx) * 100)
-    const percentY = toFixed((y.reverse ? 1 - ny : ny) * 100)
-
-    let areaProps: XYPadAreaProps = {}
-    let thumbProps: XYPadThumbProps = {}
-    if (children != undefined) {
-      React.Children.forEach(children, (child) => {
-        if (React.isValidElement(child)) {
-          if (child.type == Thumb) {
-            thumbProps = child.props as XYPadThumbProps
-          } else if (child.type == Area) {
-            areaProps = child.props as XYPadAreaProps
-          } else {
-            throw new Error('only <XYPadThumb> or <XYPadArea>')
-          }
-        } else {
-          throw new Error('children is an invalid element.')
-        }
-      })
-    }
+    const min = useMemo(() => toXY(_min), [_min])
+    const max = useMemo(() => toXY(_max), [_max])
+    const step = useMemo(() => toXY(_step), [_step])
+    const scale = useMemo(() => toXY(_scale), [_scale])
+    const reverse = useMemo(() => toXY(_reverse), [_reverse])
+
+    const percent = useMemo((): XY<number> => {
+      const normalized = [0, 1].map((i) =>
+        scale[i].normalize(value[i], min[i], max[i]),
+      )
+      return [0, 1].map((i) =>
+        toFixed((reverse[i] ? 1 - normalized[i] : normalized[i]) * 100),
+      ) as XY<number>
+    }, [value, min, max, scale, reverse])
 
     // --- internal functions ---
-    const onDrag = useCallback(
-      (nx: number, ny: number) => {
-        if (!onChange || readonly) return
-        const vx = rawValue(x.reverse ? 1 - nx : nx, x.min, x.max, x.skew)
-        const vy = rawValue(y.reverse ? 1 - ny : ny, y.min, y.max, y.skew)
-        const newX = clamp(stepValue(vx, x.step), x.min, x.max)
-        const newY = clamp(stepValue(vy, y.step), y.min, y.max)
-        onChange(newX, newY)
-      },
-      [
-        onChange,
-        readonly,
-        x.max,
-        x.min,
-        x.reverse,
-        x.skew,
-        x.step,
-        y.max,
-        y.min,
-        y.reverse,
-        y.skew,
-        y.step,
-      ],
+    // `AxisOptions` extends `ValueRange`, so the same pair also describes the
+    // scaling for `applyDelta`. Its `reverse` only concerns the drag, where
+    // positions follow the screen; the key and wheel handlers below flip the
+    // direction themselves.
+    const axis = useMemo(
+      (): XY<AxisOptions> =>
+        [0, 1].map((i) => ({
+          min: min[i],
+          max: max[i],
+          step: step[i],
+          scale: scale[i],
+          reverse: reverse[i],
+        })) as XY<AxisOptions>,
+      [min, max, step, scale, reverse],
     )
 
-    const updateValueByEvent = useCallback(
-      (
-        eventType: InputEventOption[0],
-        target: Required<ValueOptions>,
-        x: number,
-      ) => {
-        let v
-        if (eventType == 'normalized') {
-          const n = normalizeValue(
-            target.value,
-            target.min,
-            target.max,
-            target.skew,
-          )
-          v = rawValue(n + x, target.min, target.max, target.skew)
-        } else {
-          v = target.value + x
-        }
-        return clamp(stepValue(v, target.step), target.min, target.max)
-      },
-      [],
+    const withAxis = useCallback(
+      (axis: 0 | 1, next: number): XY<number> =>
+        axis == 0 ? [next, value[1]] : [value[0], next],
+      [value],
+    )
+
+    /** @param i 0 = x, 1 = y */
+    const nudge = useCallback(
+      (i: 0 | 1, direction: number, option: InputEventOption): XY<number> =>
+        withAxis(i, applyDelta(value[i], direction, option, axis[i])),
+      [value, axis, withAxis],
     )
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        if (!onChange || readonly) return
+        if (!onChange || readonly || !keyboard) return
         const key = event.key
         if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
-          const isHorizontal = key == 'ArrowRight' || key == 'ArrowLeft'
-          const target = isHorizontal ? x : y
-          if (!target.keyboard) return
+          const i: 0 | 1 = key == 'ArrowRight' || key == 'ArrowLeft' ? 0 : 1
           event.preventDefault()
-          let delta = target.keyboard[1]
-          if (key == 'ArrowLeft' || key == 'ArrowUp') delta *= -1
-          if (target.reverse) delta *= -1
-          const newValue = updateValueByEvent(target.keyboard[0], target, delta)
-          if (isHorizontal) {
-            onChange(newValue, y.value)
-          } else {
-            onChange(x.value, newValue)
-          }
+          let direction = 1
+          if (key == 'ArrowLeft' || key == 'ArrowUp') direction *= -1
+          if (reverse[i]) direction *= -1
+          onChange(nudge(i, direction, keyboard))
         }
       },
-      [onChange, readonly, x, y, updateValueByEvent],
+      [onChange, readonly, keyboard, reverse, nudge],
     )
 
     // --- hooks ---
-    const { refCallback: dragRefCallback } = useDragWithElement<HTMLDivElement>(
-      {
-        baseElementRef: areaElementRef,
-        cursor: readonly ? undefined : externalStyles.cursor,
-        updateOnPointerDown: true,
-        onDrag: onDrag,
-        onDragStart: (nx, ny) => {
-          if (readonly) return
-
-          if (externalStyles.userSelectNone) addUserSelectNone()
-
-          thumbRef.current?.focus()
-
-          const valueX = clamp(
-            stepValue(rawValue(nx, x.min, x.max, x.skew), x.step),
-            x.min,
-            x.max,
-          )
-          const valueY = clamp(
-            stepValue(rawValue(ny, y.min, y.max, y.skew), y.step),
-            y.min,
-            y.max,
-          )
 
-          onDragStart?.(valueX, valueY)
-        },
-        onDragEnd: (nx, ny) => {
-          if (readonly) return
-
-          if (externalStyles.userSelectNone) removeUserSelectNone()
-
-          const valueX = clamp(
-            stepValue(rawValue(nx, x.min, x.max, x.skew), x.step),
-            x.min,
-            x.max,
-          )
-          const valueY = clamp(
-            stepValue(rawValue(ny, y.min, y.max, y.skew), y.step),
-            y.min,
-            y.max,
-          )
-          onDragEnd?.(valueX, valueY)
-        },
+    const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
+      axis,
+      baseElementRef: areaRef,
+      updateOnPointerDown: true,
+      cursor: readonly ? undefined : externalStyles.cursor,
+      onChange: (v) => {
+        if (readonly) return
+        onChange?.(v)
       },
-    )
+      onDragStart: (v) => {
+        if (readonly) return
+        if (externalStyles.userSelectNone) addUserSelectNone()
+        thumbRef.current?.focus()
+        onDragStart?.(v)
+      },
+      onDragEnd: (v) => {
+        if (readonly) return
+        if (externalStyles.userSelectNone) removeUserSelectNone()
+        onDragEnd?.(v)
+      },
+    })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
-      if (!onChange || readonly) return
-      const target = event.shiftKey ? x : y
-      if (!target.wheel) return
+      if (!onChange || readonly || !wheel) return
+      const i: 0 | 1 = event.shiftKey ? 0 : 1
       event.preventDefault()
-      let delta = target.wheel[1]
-      if (event.deltaY < 0) delta *= -1
-      if (target.reverse) delta *= -1
-      const newValue = updateValueByEvent(target.wheel[0], target, delta)
-      if (event.shiftKey) {
-        onChange(newValue, y.value)
-      } else {
-        onChange(x.value, newValue)
-      }
-    })
+      let direction = 1
+      if (event.deltaY < 0) direction *= -1
+      if (reverse[i]) direction *= -1
+      onChange(nudge(i, direction, wheel))
+    }, WHEEL_OPTIONS)
+
+    // Composed once, so React attaches the refs a single time instead of
+    // detaching and re-attaching on every render.
+    const rootRefCallback = useComposedRefs<HTMLDivElement>(
+      rootRef,
+      dragRefCallback,
+      wheelRefCallback,
+    )
+
+    const context = useMemo(
+      () => ({
+        value,
+        min,
+        max,
+        step,
+        scale,
+        reverse,
+        disabled,
+        readonly,
+        percent,
+        areaRef,
+        thumbRef,
+      }),
+      [value, min, max, step, scale, reverse, disabled, readonly, percent],
+    )
 
     useImperativeHandle(forwardedRef, () => {
       return {
@@ -300,52 +278,33 @@ export const Root = forwardRef<XYPadMethods, Props>(
     }, [])
 
     return (
-      // eslint-disable-next-line jsx-a11y/no-static-element-interactions
-      <div
-        className={clsx('tremolo-xy-pad', className)}
-        ref={composeRefs(rootRef, wheelRefCallback, dragRefCallback)}
-        tabIndex={-1}
-        aria-disabled={disabled}
-        aria-readonly={readonly}
-        style={{
-          margin: `calc(${styleHelper(thumbProps?.size ?? 22)} / 2)`, // half thumb size
-          cursor: readonly ? 'not-allowed' : 'pointer',
-          WebkitTapHighlightColor: 'transparent',
-          ...style,
-        }}
-        onPointerDown={onPointerDown}
-        onKeyDown={(event) => {
-          handleKeyDown(event)
-          onKeyDown?.(event)
-        }}
-        onFocus={(event) => {
-          thumbRef.current?.focus()
-          onFocus?.(event)
-        }}
-        onBlur={(event) => {
-          thumbRef.current?.blur()
-          onBlur?.(event)
-        }}
-        {...props}
-      >
-        <div className="tremolo-xy-pad-area-wrapper" ref={areaElementRef}>
-          <Area
-            __thumb={
-              <Thumb
-                ref={thumbRef}
-                __disabled={disabled}
-                __readonly={readonly}
-                __css={{
-                  top: `${percentY}%`,
-                  left: `${percentX}%`,
-                }}
-                {...thumbProps}
-              />
-            }
-            {...areaProps}
-          />
+      <XYPadProvider value={context}>
+        {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
+        <div
+          className={clsx('tremolo-xy-pad', className)}
+          ref={rootRefCallback}
+          tabIndex={-1}
+          aria-disabled={disabled}
+          aria-readonly={readonly}
+          style={style}
+          onPointerDown={onPointerDown}
+          onKeyDown={(event) => {
+            handleKeyDown(event)
+            onKeyDown?.(event)
+          }}
+          onFocus={(event) => {
+            thumbRef.current?.focus()
+            onFocus?.(event)
+          }}
+          onBlur={(event) => {
+            thumbRef.current?.blur()
+            onBlur?.(event)
+          }}
+          {...props}
+        >
+          {children}
         </div>
-      </div>
+      </XYPadProvider>
     )
   },
 )
@@ -361,3 +320,4 @@ export const XYPad = {
 
 export { type XYPadThumbProps, type XYPadThumbMethods } from './Thumb'
 export { type XYPadAreaProps } from './Area'
+export { useXYPadContext, type XY, type XYInput } from './context'

package/src/hooks/useDrag.ts

@@ -2,7 +2,7 @@ import { useEffect, useState } from 'react'
 
 import { createDrag } from '@tremolo-ui/dom'
 
-import { useCallbackRef } from './useCallbackRef'
+import { useCallbackRef } from './_internal/useCallbackRef'
 
 interface UseDragProps {
   /**