@tremolo-ui/react 0.4.0 → 0.5.0

package/src/components/Slider/index.tsx

@@ -3,33 +3,33 @@ import React, {
   ComponentPropsWithoutRef,
   CSSProperties,
   forwardRef,
-  ReactElement,
+  ReactNode,
   useCallback,
   useImperativeHandle,
   useMemo,
   useRef,
 } from 'react'
 
+import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
-  clamp,
-  normalizeValue,
-  rawValue,
-  stepValue,
+  applyDelta,
+  linearScale,
   toFixed,
   InputEventOption,
-  styleHelper,
   xor,
+  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 { useComposedRefs } from '../_util/composeRefs'
 
 import { SliderProvider } from './context'
-import { Scale } from './Scale'
-import { ScaleOption } from './ScaleOption'
-import { Thumb, SliderThumbMethods, SliderThumbProps } from './Thumb'
-import { Track, SliderTrackProps } from './Track'
+import { Marks } from './Marks'
+import { MarksOption } from './MarksOption'
+import { Thumb, SliderThumbMethods } from './Thumb'
+import { Track } from './Track'
 
 const defaultExternalStyles: SliderProps['externalStyles'] = {
   userSelectNone: true,
@@ -44,7 +44,16 @@ export interface SliderProps {
 
   // optional
   step?: number
-  skew?: number // TODO | SkewFunction
+  /**
+   * 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
   /**
    * slider orientation
    * aria-orientation property is also applied.
@@ -84,9 +93,18 @@ export interface SliderProps {
   onChange?: (value: number) => void
   onDragStart?: (value: number) => void
   onDragEnd?: (value: number) => void
-  /** \<SliderThumb /> | \<SliderTrack /> */
-  children?: ReactElement | ReactElement[]
-  // ReactElement<typeof SliderThumb, typeof SliderTrack>[]
+  /**
+   * The slider renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <Slider.Root value={value} min={0} max={100} onChange={setValue}>
+   *   <Slider.Track>
+   *     <Slider.Thumb />
+   *   </Slider.Track>
+   * </Slider.Root>
+   */
+  children: ReactNode
 }
 
 export interface SliderMethods {
@@ -97,14 +115,20 @@ export interface SliderMethods {
 type Props = SliderProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof SliderProps>
 
-const Root = forwardRef<SliderMethods, 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<SliderMethods, Props>(
   (
     {
       value,
       min,
       max,
       step = 1,
-      skew = 1,
+      scale = linearScale,
       vertical = false,
       reverse = false,
       externalStyles: _externalStyles,
@@ -127,13 +151,13 @@ const Root = forwardRef<SliderMethods, Props>(
     forwardedRef,
   ) => {
     // -- state and ref ---
-    const trackElementRef = useRef<HTMLDivElement>(null)
+    const trackRef = useRef<HTMLDivElement>(null)
     const thumbRef = useRef<SliderThumbMethods>(null)
 
     // --- interpret props ---
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
 
-    const p = toFixed(normalizeValue(value, min, max, skew) * 100)
+    const p = toFixed(scale.normalize(value, min, max) * 100)
     const rev = toFixed(100 - p)
     // NOTE
     // normal -> normal (right)
@@ -146,51 +170,13 @@ const Root = forwardRef<SliderMethods, Props>(
     )
     const percent = displayReversed ? rev : p
 
-    let trackProps: SliderTrackProps = {}
-    let thumbProps: SliderThumbProps = {}
-    let scaleComponent: ReactElement | undefined = undefined
-    if (children != undefined) {
-      React.Children.forEach(children, (child) => {
-        if (React.isValidElement(child)) {
-          if (child.type == Thumb) {
-            thumbProps = child.props as SliderThumbProps
-          } else if (child.type == Track) {
-            trackProps = child.props as SliderTrackProps
-          } else if (child.type == Scale) {
-            scaleComponent = child
-          } else {
-            throw new Error('only <SliderThumb> or <SliderTrack>')
-          }
-        } else {
-          throw new Error('children is an invalid element.')
-        }
-      })
-    }
-
     // --- internal functions ---
-    const onDrag = useCallback(
-      (nx: number, ny: number) => {
-        if (!onChange || readonly) return
-        const n = vertical ? ny : nx
-        const v = rawValue(displayReversed ? 1 - n : n, min, max, skew)
-        const v2 = clamp(stepValue(v, step), min, max)
-        onChange(v2)
-      },
-      [displayReversed, max, min, onChange, readonly, skew, step, vertical],
-    )
-
-    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],
+    // The pointer is normalized against the track on both axes; only the one
+    // the slider runs along is read back. `AxisOptions` extends `ValueRange`,
+    // so the same object also describes the scaling for `applyDelta`.
+    const axis: AxisOptions = useMemo(
+      () => ({ min, max, step, scale, reverse: displayReversed }),
+      [min, max, step, scale, displayReversed],
     )
 
     const handleKeyDown = useCallback(
@@ -199,64 +185,91 @@ const Root = forwardRef<SliderMethods, Props>(
         const key = event.key
         if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
           event.preventDefault()
-          let x =
-            key == 'ArrowRight' || key == 'ArrowUp' ? keyboard[1] : -keyboard[1]
-          if (reverse) x *= -1
-          onChange(updateValueByEvent(keyboard[0], x))
+          let direction = key == 'ArrowRight' || key == 'ArrowUp' ? 1 : -1
+          if (reverse) direction *= -1
+          onChange(applyDelta(value, direction, keyboard, axis))
         }
       },
-      [keyboard, onChange, readonly, reverse, updateValueByEvent],
+      [keyboard, onChange, readonly, reverse, value, axis],
     )
 
     // --- hooks ---
-    const { refCallback: dragRefCallback } = useDragWithElement<HTMLDivElement>(
-      {
-        baseElementRef: trackElementRef,
-        cursor: readonly ? undefined : externalStyles.cursor,
-        updateOnPointerDown: true,
-        onDrag: onDrag,
-        onDragStart: (nx, ny) => {
-          if (readonly) return
-          if (externalStyles.userSelectNone) addUserSelectNone()
+    const valueOf = (v: XY<number>) => v[vertical ? 1 : 0]
 
-          thumbRef.current?.focus()
-          onDragStart?.(
-            clamp(
-              stepValue(rawValue(vertical ? ny : nx, min, max, skew), step),
-              min,
-              max,
-            ),
-          )
-        },
-        onDragEnd: (nx, ny) => {
-          if (readonly) return
+    const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
+      axis,
+      baseElementRef: trackRef,
+      cursor: readonly ? undefined : externalStyles.cursor,
+      updateOnPointerDown: true,
+      onChange: (v) => {
+        if (readonly) return
+        onChange?.(valueOf(v))
+      },
+      onDragStart: (v) => {
+        if (readonly) return
+        if (externalStyles.userSelectNone) addUserSelectNone()
 
-          if (externalStyles.userSelectNone) removeUserSelectNone()
+        thumbRef.current?.focus()
+        onDragStart?.(valueOf(v))
+      },
+      onDragEnd: (v) => {
+        if (readonly) return
 
-          onDragEnd?.(
-            clamp(
-              stepValue(rawValue(vertical ? ny : nx, min, max, skew), step),
-              min,
-              max,
-            ),
-          )
-        },
+        if (externalStyles.userSelectNone) removeUserSelectNone()
+
+        onDragEnd?.(valueOf(v))
       },
-    )
+    })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
       if (!wheel || !onChange || readonly) return
       event.preventDefault()
-      let x
+      let direction
       if (!vertical && event.deltaX != 0) {
-        x = event.deltaX > 0 ? wheel[1] : -wheel[1]
+        direction = event.deltaX > 0 ? 1 : -1
       } else {
         if (event.deltaY == 0) return
-        x = event.deltaY > 0 ? -wheel[1] : wheel[1]
+        direction = event.deltaY > 0 ? -1 : 1
       }
-      if (vertical && reverse) x *= -1
-      onChange(updateValueByEvent(wheel[0], x))
-    })
+      if (vertical && reverse) direction *= -1
+      onChange(applyDelta(value, direction, wheel, axis))
+    }, 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>(
+      dragRefCallback,
+      wheelRefCallback,
+    )
+
+    const context = useMemo(
+      () => ({
+        value,
+        min,
+        max,
+        step,
+        scale,
+        vertical,
+        reverse,
+        disabled,
+        readonly,
+        percent,
+        trackRef,
+        thumbRef,
+      }),
+      [
+        value,
+        min,
+        max,
+        step,
+        scale,
+        vertical,
+        reverse,
+        disabled,
+        readonly,
+        percent,
+      ],
+    )
 
     useImperativeHandle(forwardedRef, () => {
       return {
@@ -270,22 +283,10 @@ const Root = forwardRef<SliderMethods, Props>(
     }, [])
 
     return (
-      <SliderProvider
-        min={min}
-        max={max}
-        step={step}
-        skew={skew}
-        vertical={vertical}
-        reverse={reverse}
-        disabled={disabled}
-        readonly={readonly}
-      >
+      <SliderProvider value={context}>
         <div
           className={clsx('tremolo-slider', className)}
-          ref={(div) => {
-            wheelRefCallback(div)
-            dragRefCallback(div)
-          }}
+          ref={rootRefCallback}
           tabIndex={-1}
           role="slider"
           aria-valuenow={value}
@@ -294,10 +295,8 @@ const Root = forwardRef<SliderMethods, Props>(
           aria-orientation={vertical ? 'vertical' : 'horizontal'}
           aria-disabled={disabled}
           aria-readonly={readonly}
-          style={{
-            margin: `calc(${styleHelper(thumbProps?.size ?? 22)} / 2)`, // half thumb size
-            ...style,
-          }}
+          data-vertical={vertical}
+          style={style}
           onPointerDown={onPointerDown}
           onKeyDown={(event) => {
             handleKeyDown(event)
@@ -313,25 +312,7 @@ const Root = forwardRef<SliderMethods, Props>(
           }}
           {...props}
         >
-          <div
-            style={{
-              display: 'flex',
-              flexDirection: vertical ? 'row' : 'column',
-              width: !vertical ? '100%' : undefined,
-              height: vertical ? '100%' : undefined,
-            }}
-          >
-            <div className="tremolo-slider-track-wrapper" ref={trackElementRef}>
-              <Track
-                __percent={percent}
-                __thumb={
-                  <Thumb ref={thumbRef} __percent={percent} {...thumbProps} />
-                }
-                {...trackProps}
-              />
-            </div>
-            {scaleComponent}
-          </div>
+          {children}
         </div>
       </SliderProvider>
     )
@@ -345,13 +326,13 @@ export const Slider = {
   Root,
   Thumb,
   Track,
-  Scale,
-  ScaleOption,
+  Marks,
+  MarksOption,
 }
 
 export { useSliderContext } from './context'
 export { type SliderThumbMethods, type SliderThumbProps } from './Thumb'
 export { type SliderTrackProps } from './Track'
-export { type ScaleProps } from './Scale'
-export { type ScaleOptionProps } from './ScaleOption'
-export { type ScaleOptions, type ScaleType } from './type'
+export { type MarksProps } from './Marks'
+export { type MarksOptionProps } from './MarksOption'
+export { type MarksOptions, type MarksType } from './type'

package/src/components/Slider/type.ts

@@ -1,17 +1,17 @@
 import { decimalPart, toFixed } from '@tremolo-ui/functions'
 
-export type ScaleType = 'mark' | 'mark-number' | 'number'
-export type ScaleOptions = ['step', ScaleType] | [number, ScaleType]
+export type MarksType = 'mark' | 'mark-number' | 'number'
+export type MarksOptions = ['step', MarksType] | [number, MarksType]
 
 export function generateOptionsList(
-  options: ScaleOptions,
+  options: MarksOptions,
   min: number,
   max: number,
   step: number,
 ) {
   const optionsList: {
     value: number
-    type: ScaleType
+    type: MarksType
   }[] = []
   const per = options[0] == 'step' ? step : options[0]
   const count = Math.floor(max / per) - Math.ceil(min / per) + 1

package/src/components/XYPad/Area.tsx

@@ -1,5 +1,9 @@
 import clsx from 'clsx'
-import { ComponentPropsWithoutRef, CSSProperties, ReactElement } from 'react'
+import { ComponentPropsWithoutRef, CSSProperties, ReactNode, Ref } from 'react'
+
+import { useComposedRefs } from '../_util/composeRefs'
+
+import { useXYPadContext } from './context'
 
 export interface XYPadAreaProps {
   width?: number | string
@@ -7,10 +11,9 @@ export interface XYPadAreaProps {
   color?: string
   className?: string
   style?: CSSProperties
-  children?: ReactElement
-
-  /** inherit */
-  __thumb?: ReactElement
+  /** `<XYPad.Thumb />` goes here. */
+  children?: ReactNode
+  ref?: Ref<HTMLDivElement>
 }
 
 export function Area({
@@ -20,12 +23,19 @@ export function Area({
   children,
   className,
   style,
-  __thumb,
+  ref,
   ...props
 }: XYPadAreaProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>) {
+  const { areaRef } = useXYPadContext()
+
+  // The area is what the pointer position is normalized against, so the
+  // context ref is composed with any ref the caller passed.
+  const composedRef = useComposedRefs<HTMLDivElement>(ref, areaRef)
+
   return (
     <div
+      ref={composedRef}
       className={clsx('tremolo-xy-pad-area', className)}
       style={{
         ...{ '--color': color },
@@ -36,7 +46,6 @@ export function Area({
       {...props}
     >
       {children}
-      {__thumb}
     </div>
   )
 }

package/src/components/XYPad/Thumb.tsx

@@ -2,30 +2,26 @@ import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
   CSSProperties,
-  forwardRef,
   ReactNode,
+  Ref,
   useImperativeHandle,
   useRef,
 } from 'react'
 
-export interface XYPadThumbProps {
-  size?: number | string
-  width?: number | string
-  height?: number | string
+import { useXYPadContext } 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.
+   */
   color?: string
 
   wrapperClassName?: string
   wrapperStyle?: CSSProperties
 
   children?: ReactNode
-
-  /** @internal */
-  __disabled?: boolean
-  /** @internal */
-  __readonly?: boolean
-  /** @internal */
-  __css?: CSSProperties
+  ref?: Ref<XYPadThumbMethods>
 }
 
 export interface XYPadThumbMethods {
@@ -36,67 +32,59 @@ export interface XYPadThumbMethods {
 type Props = XYPadThumbProps &
   Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadThumbProps>
 
-export const Thumb = forwardRef<XYPadThumbMethods, Props>(
-  (
-    {
-      size,
-      width = 22,
-      height = 22,
-      color,
-      children,
-      wrapperClassName,
-      wrapperStyle,
-      className,
-      style,
-      __disabled,
-      __readonly,
-      __css,
-      ...props
-    }: Props,
-    ref,
-  ) => {
-    const wrapperRef = useRef<HTMLDivElement>(null)
+export function Thumb({
+  color,
+  children,
+  wrapperClassName,
+  wrapperStyle,
+  className,
+  style,
+  ref,
+  ...props
+}: Props) {
+  const elementRef = useRef<HTMLDivElement>(null)
+  const { disabled, readonly, percent, thumbRef } = useXYPadContext()
 
-    useImperativeHandle(ref, () => {
-      return {
-        focus() {
-          wrapperRef.current?.focus()
-        },
-        blur() {
-          wrapperRef.current?.blur()
-        },
-      }
-    }, [])
+  const methods = () => ({
+    focus() {
+      elementRef.current?.focus()
+    },
+    blur() {
+      elementRef.current?.blur()
+    },
+  })
 
-    return (
-      <div
-        className={clsx('tremolo-xy-pad-thumb-wrapper', wrapperClassName)}
-        style={{
-          ...__css,
-          ...wrapperStyle,
-        }}
-        {...props}
-      >
-        {children ? (
-          children
-        ) : (
-          // default thumb
-          <div
-            ref={wrapperRef}
-            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 },
-              width: size ?? width,
-              height: size ?? height,
-              ...style,
-            }}
-          ></div>
-        )}
-      </div>
-    )
-  },
-)
+  useImperativeHandle(ref, methods, [])
+  // Root focuses the thumb when a drag starts, wherever the user placed it.
+  useImperativeHandle(thumbRef, methods, [])
+
+  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>
+  )
+}

package/src/components/XYPad/context.tsx

@@ -0,0 +1,46 @@
+import { createContext, RefObject, useContext } from 'react'
+
+import { toXY, type XY, type XYInput } from '@tremolo-ui/dom'
+import type { Scale } from '@tremolo-ui/functions'
+
+import type { XYPadThumbMethods } from './Thumb'
+
+export { toXY, type XY, type XYInput }
+
+export type XYPadContextValue = {
+  value: XY<number>
+  min: XY<number>
+  max: XY<number>
+  step: XY<number>
+  /** How the value of each axis is distributed across the travel. */
+  scale: XY<Scale>
+  reverse: XY<boolean>
+  disabled: boolean
+  readonly: boolean
+
+  /**
+   * Position of the thumb, 0-100 per axis, already accounting for `reverse`.
+   */
+  percent: XY<number>
+
+  /** `Area` registers its element here; `Root` normalizes the pointer against it. */
+  areaRef: RefObject<HTMLDivElement | null>
+  /** `Thumb` registers itself here; `Root` focuses it when a drag starts. */
+  thumbRef: RefObject<XYPadThumbMethods | null>
+}
+
+const XYPadContext = createContext<XYPadContextValue | null>(null)
+
+export const XYPadProvider = XYPadContext.Provider
+
+/**
+ * Everything here is derived during render, so there is no state to keep in
+ * sync: `value` comes from the props of `Root` and the rest follows from it.
+ */
+export function useXYPadContext(): XYPadContextValue
+export function useXYPadContext<T>(selector: (state: XYPadContextValue) => T): T
+export function useXYPadContext<T>(selector?: (state: XYPadContextValue) => T) {
+  const context = useContext(XYPadContext)
+  if (!context) throw new Error('Missing XYPadContext.Provider in the tree')
+  return selector ? selector(context) : context
+}