@tremolo-ui/react 0.5.0 → 0.6.0

package/src/components/XYPad/Thumb.tsx

@@ -1,27 +1,50 @@
-import clsx from 'clsx'
 import {
+  AriaAttributes,
   ComponentPropsWithoutRef,
   CSSProperties,
+  forwardRef,
   ReactNode,
-  Ref,
   useImperativeHandle,
   useRef,
 } from 'react'
 
-import { useXYPadContext } from './context'
+import { useCheckPlacement } from '../_util/Placement'
+import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
+
+import { toXY, useXYPadContext, type XYInput } from './context'
 
 export interface XYPadThumbProps {
   /**
-   * Size comes from the `--thumb-size` CSS variable on `XYPad.Root`, so that
-   * the root can reserve the matching amount of space around the area.
+   * Sets `--color`, for the theme to colour the thumb with. The size is not
+   * set here but by `--thumb-size` on `XYPad.Root`, so that the root can leave
+   * the matching room around the area.
    */
   color?: string
 
-  wrapperClassName?: string
-  wrapperStyle?: CSSProperties
-
+  className?: string
+  style?: CSSProperties
+  /**
+   * Rendered inside the thumb. The thumb is one element either way, so what
+   * is passed here is decoration on top of it rather than a replacement for
+   * it — `className` and `style` are how its own appearance is changed.
+   */
   children?: ReactNode
-  ref?: Ref<XYPadThumbMethods>
+
+  /**
+   * The accessible name of each axis, as `[x, y]`. There are two range inputs
+   * inside the thumb, so each takes a name of its own; a single string names
+   * them both, which is rarely what you want.
+   */
+  'aria-label'?: XYInput<AriaAttributes['aria-label']>
+  /** The ids of what labels each axis, as `[x, y]` or one for both. */
+  'aria-labelledby'?: XYInput<AriaAttributes['aria-labelledby']>
+  /** The ids of what describes each axis, as `[x, y]` or one for both. */
+  'aria-describedby'?: XYInput<AriaAttributes['aria-describedby']>
+  /**
+   * What the value of each axis means, when the number does not say it, as
+   * `[x, y]` or one for both.
+   */
+  'aria-valuetext'?: XYInput<AriaAttributes['aria-valuetext']>
 }
 
 export interface XYPadThumbMethods {
@@ -32,59 +55,109 @@ export interface XYPadThumbMethods {
 type Props = XYPadThumbProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadThumbProps>
 
-export function Thumb({
-  color,
-  children,
-  wrapperClassName,
-  wrapperStyle,
-  className,
-  style,
-  ref,
-  ...props
-}: Props) {
-  const elementRef = useRef<HTMLDivElement>(null)
-  const { disabled, readonly, percent, thumbRef } = useXYPadContext()
-
-  const methods = () => ({
-    focus() {
-      elementRef.current?.focus()
+export const Thumb = /* @__PURE__ */ forwardRef<XYPadThumbMethods, Props>(
+  function Thumb(
+    {
+      color,
+      children,
+      className,
+      style,
+      'aria-label': ariaLabel,
+      'aria-labelledby': ariaLabelledby,
+      'aria-describedby': ariaDescribedby,
+      'aria-valuetext': ariaValuetext,
+      ...props
     },
-    blur() {
-      elementRef.current?.blur()
-    },
-  })
+    forwardedRef,
+  ) {
+    const xInputRef = useRef<HTMLInputElement>(null)
+    const yInputRef = useRef<HTMLInputElement>(null)
+    const {
+      value,
+      min,
+      max,
+      step,
+      disabled,
+      readonly,
+      onChange,
+      percent,
+      thumbRef,
+    } = useXYPadContext()
 
-  useImperativeHandle(ref, methods, [])
-  // Root focuses the thumb when a drag starts, wherever the user placed it.
-  useImperativeHandle(thumbRef, methods, [])
+    // The thumb is positioned against the area.
+    useCheckPlacement('XYPad.Thumb', 'XYPad.Area')
 
-  return (
-    <div
-      className={clsx('tremolo-xy-pad-thumb-wrapper', wrapperClassName)}
-      style={{
-        left: `${percent[0]}%`,
-        top: `${percent[1]}%`,
-        ...wrapperStyle,
-      }}
-      {...props}
-    >
-      {children ? (
-        children
-      ) : (
-        // default thumb
-        <div
-          ref={elementRef}
-          className={clsx('tremolo-xy-pad-thumb', className)}
-          // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
-          tabIndex={0}
-          aria-disabled={disabled}
-          aria-readonly={readonly}
-          style={{
-            ...{ '--color': color },
-            ...style,
-          }}
-        ></div>
-      )}
-    </div>
-  )
-}
+    // Per axis, since the thumb holds one input for each.
+    const labels = toXY(ariaLabel)
+    const labelledby = toXY(ariaLabelledby)
+    const describedby = toXY(ariaDescribedby)
+    const valueText = toXY(ariaValuetext)
+
+    const methods = () => ({
+      focus() {
+        if (!disabled) xInputRef.current?.focus()
+      },
+      blur() {
+        xInputRef.current?.blur()
+        yInputRef.current?.blur()
+      },
+    })
+
+    useImperativeHandle(forwardedRef, methods, [disabled])
+    // Root focuses the thumb when a drag starts, wherever the user placed it.
+    useImperativeHandle(thumbRef, methods, [disabled])
+
+    return (
+      <div
+        className={className}
+        data-disabled={disabled ? '' : undefined}
+        data-readonly={readonly ? '' : undefined}
+        {...props}
+        style={{
+          ...{ '--color': color },
+          // Not a style but the mechanics of the position below: the thumb is
+          // placed by a percentage of the area, which needs it out of flow and
+          // measured from its own centre.
+          position: 'absolute',
+          translate: 'var(--translate, -50% -50%)',
+          zIndex: 100,
+          ...style,
+          // Where the thumb sits is the component's decision, not a style: a
+          // `left` from the caller would take it off the area, so it is written
+          // after theirs.
+          left: `${percent[0]}%`,
+          top: `${percent[1]}%`,
+        }}
+      >
+        {([0, 1] as const).map((axis) => (
+          <VisuallyHiddenRangeInput
+            key={axis}
+            ref={axis === 0 ? xInputRef : yInputRef}
+            data-axis={axis === 0 ? 'x' : 'y'}
+            value={value[axis]}
+            min={min[axis]}
+            max={max[axis]}
+            step={step[axis]}
+            disabled={disabled}
+            aria-readonly={readonly}
+            aria-orientation={axis === 0 ? 'horizontal' : 'vertical'}
+            aria-label={labels[axis] ?? (axis === 0 ? 'x' : 'y')}
+            aria-labelledby={labelledby[axis]}
+            aria-describedby={describedby[axis]}
+            aria-valuetext={valueText[axis]}
+            onChange={(event) => {
+              if (readonly) {
+                event.currentTarget.value = String(value[axis])
+                return
+              }
+              const next = [...value] as [number, number]
+              next[axis] = event.currentTarget.valueAsNumber
+              onChange?.(next)
+            }}
+          />
+        ))}
+        {children}
+      </div>
+    )
+  },
+)

package/src/components/XYPad/context.tsx

@@ -17,6 +17,7 @@ export type XYPadContextValue = {
   reverse: XY<boolean>
   disabled: boolean
   readonly: boolean
+  onChange?: (value: XY<number>) => void
 
   /**
    * Position of the thumb, 0-100 per axis, already accounting for `reverse`.
@@ -29,7 +30,9 @@ export type XYPadContextValue = {
   thumbRef: RefObject<XYPadThumbMethods | null>
 }
 
-const XYPadContext = createContext<XYPadContextValue | null>(null)
+const XYPadContext = /* @__PURE__ */ createContext<XYPadContextValue | null>(
+  null,
+)
 
 export const XYPadProvider = XYPadContext.Provider
 

package/src/components/XYPad/index.tsx

@@ -1,6 +1,6 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
   ReactNode,
   Ref,
@@ -16,20 +16,27 @@ import {
   linearScale,
   toFixed,
   InputEventOption,
+  ModifierState,
+  type ModifierValue,
+  selectModifier,
   type Scale,
 } from '@tremolo-ui/functions'
 
+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 { useComposedRefs } from '../_util/composeRefs'
+import {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+} from '../../input-event'
 
 import { Area } from './Area'
 import { toXY, XY, XYInput, XYPadProvider } from './context'
 import { Thumb, XYPadThumbMethods } from './Thumb'
 
 const defaultExternalStyles: XYPadProps['externalStyles'] = {
-  userSelectNone: true,
   cursor: 'pointer',
 }
 
@@ -40,13 +47,23 @@ const defaultExternalStyles: XYPadProps['externalStyles'] = {
  * value applies to both axes.
  */
 export interface XYPadProps {
+  /** The current value as `[x, y]`. The pad shows only this, so update it from `onChange`. */
   value: XY<number>
+  /** The value at the start of each axis, as `[x, y]` or one number for both. */
   min: XYInput<number>
+  /** The value at the end of each axis, as `[x, y]` or one number for both. */
   max: XYInput<number>
 
+  /**
+   * Granularity of each axis, as `[x, y]` or one number for both. A drag, the
+   * wheel and the arrow keys snap the value to multiples of it.
+   *
+   * @default 1
+   */
   step?: XYInput<number>
   /**
-   * How the value of each axis is distributed across the travel.
+   * How the value of each axis is distributed across the travel, as `[x, y]`
+   * or one scale for both.
    *
    * Pick one of the scales from `@tremolo-ui/functions`: `linearScale`,
    * `exponentialScale`, `curveScale(n)`, `symmetricSkewScale(n)`, or
@@ -55,29 +72,88 @@ export interface XYPadProps {
    * @default linearScale
    */
   scale?: XYInput<Scale>
+  /**
+   * Grow an axis the other way, as `[x, y]` or one for both. By default x grows
+   * rightwards and y downwards. The arrow keys follow the direction on screen.
+   *
+   * @default false
+   */
   reverse?: XYInput<boolean>
 
   /**
-   * wheel control option. Shift selects the x axis.
-   * 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 pad leaves it alone.
+   * Scrolling sideways, or with shift held, moves x; otherwise it moves y.
+   *
+   * `['raw', n]` moves the value by `n`, and `['normalized', n]` by `n` of the
+   * range of that axis. The result is snapped to `step`, except for an amount
+   * set on a modifier key (`{ default: …, alt: … }`). `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 pointer position itself, which is what a drag normally is here.
+   * **Anything else turns the drag relative**: `0.1` makes the same movement
+   * cover a tenth of the travel, so the value stops following the pointer and
+   * starts moving a tenth as fast. 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. **The
+   * pointer and the value stay apart for the rest of the drag** — snapping
+   * them back together on release would move the value nobody asked to move.
+   *
+   * @default { default: 1, shift: 0.1 }
    */
-  keyboard?: InputEventOption | null
+  dragSensitivity?: ModifierValue<number>
 
+  /**
+   * How much one arrow key press moves the value. Left and right move x, up
+   * and down move y.
+   *
+   * `['raw', n]` moves the value by `n`, and `['normalized', n]` by `n` of the
+   * range of that axis. 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
+
+  /**
+   * The cursor to show while dragging. It is set on the dragged element, so it
+   * stays while the pointer is outside the pad.
+   *
+   * @default { cursor: 'pointer' }
+   */
   externalStyles?: {
-    userSelectNone?: boolean
-    cursor?: Cursor
+    cursor?: CSSProperties['cursor']
   }
 
+  /**
+   * Make the pad unchangeable and remove its thumb from the tab order.
+   * The parts carry `data-disabled` while it is set.
+   */
   disabled?: boolean
+  /**
+   * Make the pad unchangeable while leaving its thumb focusable.
+   * The parts carry `data-readonly` while it is set.
+   */
   readonly?: boolean
 
+  /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: XY<number>) => void
+  /** Called when a drag starts, with the value where the area was pressed. */
   onDragStart?: (value: XY<number>) => void
+  /** Called when the drag ends, with the value it ended on. */
   onDragEnd?: (value: XY<number>) => void
 
   /**
@@ -109,7 +185,7 @@ type Props = XYPadProps &
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = forwardRef<XYPadMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
   (
     {
       value,
@@ -118,8 +194,9 @@ export const Root = forwardRef<XYPadMethods, Props>(
       step: _step = 1,
       scale: _scale = linearScale,
       reverse: _reverse = false,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       className,
       style,
       externalStyles: _externalStyles,
@@ -144,6 +221,7 @@ export const Root = forwardRef<XYPadMethods, Props>(
 
     // --- interpret props ---
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
+    const inactive = disabled || readonly
 
     const min = useMemo(() => toXY(_min), [_min])
     const max = useMemo(() => toXY(_max), [_max])
@@ -177,33 +255,61 @@ export const Root = forwardRef<XYPadMethods, Props>(
       [min, max, step, scale, reverse],
     )
 
+    useCheckSteps({
+      component: 'XYPad',
+      axis: 'x',
+      range: axis[0],
+      keyboard,
+      wheel,
+    })
+    useCheckSteps({
+      component: 'XYPad',
+      axis: 'y',
+      range: axis[1],
+      keyboard,
+      wheel,
+    })
+
     const withAxis = useCallback(
       (axis: 0 | 1, next: number): XY<number> =>
-        axis == 0 ? [next, value[1]] : [value[0], next],
+        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])),
+      (
+        i: 0 | 1,
+        direction: number,
+        option: ModifierValue<InputEventOption>,
+        modifiers: ModifierState,
+      ): XY<number> =>
+        withAxis(
+          i,
+          applyDelta(value[i], direction, option, axis[i], modifiers),
+        ),
       [value, axis, withAxis],
     )
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        if (!onChange || readonly || !keyboard) return
         const key = event.key
-        if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
-          const i: 0 | 1 = key == 'ArrowRight' || key == 'ArrowLeft' ? 0 : 1
-          event.preventDefault()
-          let direction = 1
-          if (key == 'ArrowLeft' || key == 'ArrowUp') direction *= -1
-          if (reverse[i]) direction *= -1
-          onChange(nudge(i, direction, keyboard))
-        }
+        if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
+          return
+
+        // The key picks the axis, whichever of the two inputs holds the
+        // focus: the pad is one control to the person moving it, and the focus
+        // lands on the x input, so reading the axis off the input would leave
+        // the y axis with no keys at all.
+        const i: 0 | 1 = key === 'ArrowRight' || key === 'ArrowLeft' ? 0 : 1
+        event.preventDefault()
+        if (!onChange || inactive || !keyboard) return
+        let direction = 1
+        if (key === 'ArrowLeft' || key === 'ArrowUp') direction *= -1
+        if (reverse[i]) direction *= -1
+        onChange(nudge(i, direction, keyboard, event))
       },
-      [onChange, readonly, keyboard, reverse, nudge],
+      [onChange, inactive, keyboard, reverse, nudge],
     )
 
     // --- hooks ---
@@ -211,33 +317,41 @@ export const Root = forwardRef<XYPadMethods, Props>(
     const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
       axis,
       baseElementRef: areaRef,
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
       updateOnPointerDown: true,
-      cursor: readonly ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      shouldStart: () => !inactive,
       onChange: (v) => {
-        if (readonly) return
+        if (inactive) return
         onChange?.(v)
       },
       onDragStart: (v) => {
-        if (readonly) return
-        if (externalStyles.userSelectNone) addUserSelectNone()
+        if (inactive) return
         thumbRef.current?.focus()
         onDragStart?.(v)
       },
       onDragEnd: (v) => {
-        if (readonly) return
-        if (externalStyles.userSelectNone) removeUserSelectNone()
+        if (inactive) return
         onDragEnd?.(v)
       },
     })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
-      if (!onChange || readonly || !wheel) return
-      const i: 0 | 1 = event.shiftKey ? 0 : 1
+      if (!onChange || inactive || !wheel) return
+      // Browsers turn shift+wheel into horizontal scrolling: `deltaY` comes
+      // out empty and `deltaX` carries the movement. Reading whichever axis
+      // moved keeps shift working as the x-axis modifier — and picks up a
+      // trackpad's own horizontal gesture, which never had a modifier.
+      const horizontal = event.deltaX !== 0
+      const delta = horizontal ? event.deltaX : event.deltaY
+      if (delta === 0) return
+      const i: 0 | 1 = horizontal || event.shiftKey ? 0 : 1
       event.preventDefault()
       let direction = 1
-      if (event.deltaY < 0) direction *= -1
+      if (delta < 0) direction *= -1
       if (reverse[i]) direction *= -1
-      onChange(nudge(i, direction, wheel))
+      onChange(nudge(i, direction, wheel, event))
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
@@ -258,34 +372,47 @@ export const Root = forwardRef<XYPadMethods, Props>(
         reverse,
         disabled,
         readonly,
+        onChange,
         percent,
         areaRef,
         thumbRef,
       }),
-      [value, min, max, step, scale, reverse, disabled, readonly, percent],
+      [
+        value,
+        min,
+        max,
+        step,
+        scale,
+        reverse,
+        disabled,
+        readonly,
+        onChange,
+        percent,
+      ],
     )
 
     useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
-          thumbRef.current?.focus()
+          if (!disabled) thumbRef.current?.focus()
         },
         blur() {
           thumbRef.current?.blur()
         },
         original: rootRef,
       }
-    }, [])
+    }, [disabled])
 
     return (
       <XYPadProvider value={context}>
-        {/* eslint-disable-next-line jsx-a11y/no-static-element-interactions */}
+        {/* oxlint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the group handles pointer and keyboard input shared by its two range controls */}
         <div
-          className={clsx('tremolo-xy-pad', className)}
+          className={className}
           ref={rootRefCallback}
+          role="group"
           tabIndex={-1}
-          aria-disabled={disabled}
-          aria-readonly={readonly}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
           style={style}
           onPointerDown={onPointerDown}
           onKeyDown={(event) => {
@@ -293,7 +420,7 @@ export const Root = forwardRef<XYPadMethods, Props>(
             onKeyDown?.(event)
           }}
           onFocus={(event) => {
-            thumbRef.current?.focus()
+            if (!disabled) thumbRef.current?.focus()
             onFocus?.(event)
           }}
           onBlur={(event) => {
@@ -320,4 +447,9 @@ export const XYPad = {
 
 export { type XYPadThumbProps, type XYPadThumbMethods } from './Thumb'
 export { type XYPadAreaProps } from './Area'
-export { useXYPadContext, type XY, type XYInput } from './context'
+export {
+  useXYPadContext,
+  type XYPadContextValue,
+  type XY,
+  type XYInput,
+} from './context'