@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/Slider/index.tsx

@@ -1,92 +1,172 @@
-import clsx from 'clsx'
 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,
+  type InputEventOption,
+  type ModifierValue,
+  selectModifier,
   xor,
+  type Scale,
 } from '@tremolo-ui/functions'
 
-import { useDragWithElement } from '../../hooks/useDragWithElement'
+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 { 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,
   cursor: 'pointer',
 }
 
 export interface SliderProps {
-  // required
+  /** The current value. The slider shows only this, so update it from `onChange`. */
   value: number
+  /** The value at the start of the travel. */
   min: number
+  /** The value at the end of the travel. */
   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 // TODO | SkewFunction
   /**
-   * slider orientation
-   * aria-orientation property is also applied.
+   * 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
+  /**
+   * Run the slider vertically, with the value growing upwards. The range input
+   * inside the thumb takes its `aria-orientation` from this.
+   *
+   * @default false
    */
   vertical?: boolean
+  /**
+   * Grow the value the other way: leftwards, or downwards when `vertical`.
+   * The arrow keys follow the direction on screen.
+   *
+   * @default false
+   */
   reverse?: boolean
 
-  /** Global style to apply when dragged */
+  /**
+   * The cursor to show while dragging. It is set on the dragged element, so it
+   * stays while the pointer is outside the slider.
+   *
+   * @default { cursor: 'pointer' }
+   */
   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 slider 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 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>
 
   /**
-   * Only the appearance will change.
-   * Please consider using with readonly.
-   * aria-disabled property is also applied.
+   * 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
+
+  /**
+   * Make the slider unchangeable and remove it from the tab order.
+   * The parts carry `data-disabled` while it is set.
    */
   disabled?: boolean
   /**
    * Make the value unchangeable.
-   * aria-readonly property is also applied.
+   * The parts carry `data-readonly` while it is set.
    */
   readonly?: boolean
   className?: string
   style?: CSSProperties
+  /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: number) => void
+  /** Called when a drag starts, with the value where the track was pressed. */
   onDragStart?: (value: number) => void
+  /** Called when the drag ends, with the value it ended on. */
   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 aria-label="Level" />
+   *   </Slider.Track>
+   * </Slider.Root>
+   */
+  children: ReactNode
 }
 
 export interface SliderMethods {
@@ -97,19 +177,26 @@ 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 = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
   (
     {
       value,
       min,
       max,
       step = 1,
-      skew = 1,
+      scale = linearScale,
       vertical = false,
       reverse = false,
       externalStyles: _externalStyles,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
       disabled = false,
       readonly = false,
       onChange,
@@ -127,13 +214,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 inactive = disabled || readonly
 
-    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,165 +233,143 @@ 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],
+    // 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 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: 'Slider', range: axis, keyboard, wheel })
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        if (!keyboard || !onChange || readonly) return
         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))
-        }
+        if (!['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key))
+          return
+        event.preventDefault()
+        if (!keyboard || !onChange || inactive) return
+        let direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
+        if (reverse) direction *= -1
+        onChange(applyDelta(value, direction, keyboard, axis, event))
       },
-      [keyboard, onChange, readonly, reverse, updateValueByEvent],
+      [keyboard, onChange, inactive, 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()
-
-          thumbRef.current?.focus()
-          onDragStart?.(
-            clamp(
-              stepValue(rawValue(vertical ? ny : nx, min, max, skew), step),
-              min,
-              max,
-            ),
-          )
-        },
-        onDragEnd: (nx, ny) => {
-          if (readonly) return
+    const valueOf = (v: XY<number>) => v[vertical ? 1 : 0]
 
-          if (externalStyles.userSelectNone) removeUserSelectNone()
-
-          onDragEnd?.(
-            clamp(
-              stepValue(rawValue(vertical ? ny : nx, min, max, skew), step),
-              min,
-              max,
-            ),
-          )
-        },
+    const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
+      axis,
+      baseElementRef: trackRef,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      shouldStart: () => !inactive,
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
+      updateOnPointerDown: true,
+      onChange: (v) => {
+        if (inactive) return
+        onChange?.(valueOf(v))
       },
-    )
+      onDragStart: (v) => {
+        if (inactive) return
+        thumbRef.current?.focus()
+        onDragStart?.(valueOf(v))
+      },
+      onDragEnd: (v) => {
+        if (inactive) return
+        onDragEnd?.(valueOf(v))
+      },
+    })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
-      if (!wheel || !onChange || readonly) return
+      if (!wheel || !onChange || inactive) return
       event.preventDefault()
-      let x
-      if (!vertical && event.deltaX != 0) {
-        x = event.deltaX > 0 ? wheel[1] : -wheel[1]
+      let direction
+      if (!vertical && event.deltaX !== 0) {
+        direction = event.deltaX > 0 ? 1 : -1
       } else {
-        if (event.deltaY == 0) return
-        x = event.deltaY > 0 ? -wheel[1] : wheel[1]
+        if (event.deltaY === 0) return
+        direction = event.deltaY > 0 ? -1 : 1
       }
-      if (vertical && reverse) x *= -1
-      onChange(updateValueByEvent(wheel[0], x))
-    })
+      if (reverse) direction *= -1
+      onChange(applyDelta(value, direction, wheel, axis, 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<HTMLDivElement>(
+      dragRefCallback,
+      wheelRefCallback,
+    )
+
+    const context = useMemo(
+      () => ({
+        value,
+        min,
+        max,
+        step,
+        scale,
+        vertical,
+        reverse,
+        disabled,
+        readonly,
+        onChange,
+        percent,
+        trackRef,
+        thumbRef,
+      }),
+      [
+        value,
+        min,
+        max,
+        step,
+        scale,
+        vertical,
+        reverse,
+        disabled,
+        readonly,
+        onChange,
+        percent,
+      ],
+    )
 
     useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
-          thumbRef.current?.focus()
+          if (!disabled) thumbRef.current?.focus()
         },
         blur() {
           thumbRef.current?.blur()
         },
       }
-    }, [])
+    }, [disabled])
 
     return (
-      <SliderProvider
-        min={min}
-        max={max}
-        step={step}
-        skew={skew}
-        vertical={vertical}
-        reverse={reverse}
-        disabled={disabled}
-        readonly={readonly}
-      >
+      <SliderProvider value={context}>
+        {/* oxlint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the group is the pointer and keyboard event area, while the nested range input carries its control semantics */}
         <div
-          className={clsx('tremolo-slider', className)}
-          ref={(div) => {
-            wheelRefCallback(div)
-            dragRefCallback(div)
-          }}
+          className={className}
+          ref={rootRefCallback}
+          role="group"
+          // A press lands on the track or the thumb, neither of which can hold
+          // focus, and the browser answers that by clearing the focus to the
+          // body — undoing the focus the drag just gave the input. Taking the
+          // focus here keeps it inside, and `onFocus` passes it to the input.
           tabIndex={-1}
-          role="slider"
-          aria-valuenow={value}
-          aria-valuemin={min}
-          aria-valuemax={max}
-          aria-orientation={vertical ? 'vertical' : 'horizontal'}
-          aria-disabled={disabled}
-          aria-readonly={readonly}
-          style={{
-            margin: `calc(${styleHelper(thumbProps?.size ?? 22)} / 2)`, // half thumb size
-            ...style,
-          }}
+          data-orientation={vertical ? 'vertical' : 'horizontal'}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
+          style={style}
           onPointerDown={onPointerDown}
           onKeyDown={(event) => {
             handleKeyDown(event)
             onKeyDown?.(event)
           }}
           onFocus={(event) => {
-            thumbRef.current?.focus()
+            if (!disabled) thumbRef.current?.focus()
             onFocus?.(event)
           }}
           onBlur={(event) => {
@@ -313,25 +378,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 +392,13 @@ export const Slider = {
   Root,
   Thumb,
   Track,
-  Scale,
-  ScaleOption,
+  Marks,
+  MarksOption,
 }
 
-export { useSliderContext } from './context'
+export { useSliderContext, type SliderContextValue } 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 SliderMarksProps } from './Marks'
+export { type SliderMarksOptionProps } from './MarksOption'
+export { type MarksOptions } from './type'

package/src/components/Slider/type.ts

@@ -1,26 +1,44 @@
 import { decimalPart, toFixed } from '@tremolo-ui/functions'
 
-export type ScaleType = 'mark' | 'mark-number' | 'number'
-export type ScaleOptions = ['step', ScaleType] | [number, ScaleType]
+/**
+ * How `Slider.Marks` fills itself in when it is given no children: one option
+ * every `per`, or every `step` of the slider. The object form turns off the
+ * mark or the label for the whole set; a single option is customized by
+ * writing `Slider.MarksOption` out instead.
+ */
+export type MarksOptions =
+  | 'step'
+  | number
+  | {
+      per: 'step' | number
+      mark?: boolean
+      label?: boolean
+    }
 
 export function generateOptionsList(
-  options: ScaleOptions,
+  options: MarksOptions,
   min: number,
   max: number,
   step: number,
 ) {
+  const {
+    per,
+    mark = true,
+    label = true,
+  } = typeof options === 'object' ? options : { per: options }
   const optionsList: {
     value: number
-    type: ScaleType
+    mark: boolean
+    label: boolean
   }[] = []
-  const per = options[0] == 'step' ? step : options[0]
-  const count = Math.floor(max / per) - Math.ceil(min / per) + 1
+  const interval = per === 'step' ? step : per
+  const count = Math.floor(max / interval) - Math.ceil(min / interval) + 1
   for (let i = 0; i < count; i++) {
     const value = toFixed(
-      per * (Math.ceil(min / per) + i),
-      decimalPart(per)?.length,
+      interval * (Math.ceil(min / interval) + i),
+      decimalPart(interval)?.length,
     )
-    optionsList.push({ value: value, type: options[1] })
+    optionsList.push({ value: value, mark: mark, label: label })
   }
   return optionsList
 }