@tremolo-ui/react 0.5.0 → 0.6.0

package/src/components/Slider/index.tsx

@@ -1,4 +1,3 @@
-import clsx from 'clsx'
 import React, {
   ComponentPropsWithoutRef,
   CSSProperties,
@@ -15,15 +14,22 @@ import {
   applyDelta,
   linearScale,
   toFixed,
-  InputEventOption,
+  type InputEventOption,
+  type ModifierValue,
+  selectModifier,
   xor,
   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 { SliderProvider } from './context'
 import { Marks } from './Marks'
@@ -32,17 +38,23 @@ 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
   /**
    * How the value is distributed across the travel.
@@ -55,43 +67,93 @@ export interface SliderProps {
    */
   scale?: Scale
   /**
-   * slider orientation
-   * aria-orientation property is also applied.
+   * 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
   /**
    * The slider renders exactly what you compose here; there is no default
@@ -100,7 +162,7 @@ export interface SliderProps {
    * @example
    * <Slider.Root value={value} min={0} max={100} onChange={setValue}>
    *   <Slider.Track>
-   *     <Slider.Thumb />
+   *     <Slider.Thumb aria-label="Level" />
    *   </Slider.Track>
    * </Slider.Root>
    */
@@ -121,7 +183,7 @@ type Props = SliderProps &
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = forwardRef<SliderMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<SliderMethods, Props>(
   (
     {
       value,
@@ -132,8 +194,9 @@ export const Root = forwardRef<SliderMethods, Props>(
       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,
@@ -153,9 +216,9 @@ export const Root = forwardRef<SliderMethods, Props>(
     // -- state and ref ---
     const trackRef = useRef<HTMLDivElement>(null)
     const thumbRef = useRef<SliderThumbMethods>(null)
-
     // --- interpret props ---
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
+    const inactive = disabled || readonly
 
     const p = toFixed(scale.normalize(value, min, max) * 100)
     const rev = toFixed(100 - p)
@@ -179,18 +242,20 @@ export const Root = forwardRef<SliderMethods, Props>(
       [min, max, step, scale, displayReversed],
     )
 
+    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 direction = key == 'ArrowRight' || key == 'ArrowUp' ? 1 : -1
-          if (reverse) direction *= -1
-          onChange(applyDelta(value, direction, keyboard, axis))
-        }
+        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, value, axis],
+      [keyboard, onChange, inactive, reverse, value, axis],
     )
 
     // --- hooks ---
@@ -199,40 +264,38 @@ export const Root = forwardRef<SliderMethods, Props>(
     const { refCallback: dragRefCallback } = useDragValue<HTMLDivElement>({
       axis,
       baseElementRef: trackRef,
-      cursor: readonly ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      shouldStart: () => !inactive,
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
       updateOnPointerDown: true,
       onChange: (v) => {
-        if (readonly) return
+        if (inactive) return
         onChange?.(valueOf(v))
       },
       onDragStart: (v) => {
-        if (readonly) return
-        if (externalStyles.userSelectNone) addUserSelectNone()
-
+        if (inactive) return
         thumbRef.current?.focus()
         onDragStart?.(valueOf(v))
       },
       onDragEnd: (v) => {
-        if (readonly) return
-
-        if (externalStyles.userSelectNone) removeUserSelectNone()
-
+        if (inactive) return
         onDragEnd?.(valueOf(v))
       },
     })
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
-      if (!wheel || !onChange || readonly) return
+      if (!wheel || !onChange || inactive) return
       event.preventDefault()
       let direction
-      if (!vertical && event.deltaX != 0) {
+      if (!vertical && event.deltaX !== 0) {
         direction = event.deltaX > 0 ? 1 : -1
       } else {
-        if (event.deltaY == 0) return
+        if (event.deltaY === 0) return
         direction = event.deltaY > 0 ? -1 : 1
       }
-      if (vertical && reverse) direction *= -1
-      onChange(applyDelta(value, direction, wheel, axis))
+      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
@@ -253,6 +316,7 @@ export const Root = forwardRef<SliderMethods, Props>(
         reverse,
         disabled,
         readonly,
+        onChange,
         percent,
         trackRef,
         thumbRef,
@@ -267,6 +331,7 @@ export const Root = forwardRef<SliderMethods, Props>(
         reverse,
         disabled,
         readonly,
+        onChange,
         percent,
       ],
     )
@@ -274,28 +339,29 @@ export const Root = forwardRef<SliderMethods, Props>(
     useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
-          thumbRef.current?.focus()
+          if (!disabled) thumbRef.current?.focus()
         },
         blur() {
           thumbRef.current?.blur()
         },
       }
-    }, [])
+    }, [disabled])
 
     return (
       <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)}
+          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}
-          data-vertical={vertical}
+          data-orientation={vertical ? 'vertical' : 'horizontal'}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
           style={style}
           onPointerDown={onPointerDown}
           onKeyDown={(event) => {
@@ -303,7 +369,7 @@ export const Root = forwardRef<SliderMethods, Props>(
             onKeyDown?.(event)
           }}
           onFocus={(event) => {
-            thumbRef.current?.focus()
+            if (!disabled) thumbRef.current?.focus()
             onFocus?.(event)
           }}
           onBlur={(event) => {
@@ -330,9 +396,9 @@ export const Slider = {
   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 MarksProps } from './Marks'
-export { type MarksOptionProps } from './MarksOption'
-export { type MarksOptions, type MarksType } from './type'
+export { type SliderMarksProps } from './Marks'
+export { type SliderMarksOptionProps } from './MarksOption'
+export { type MarksOptions } from './type'

package/src/components/Slider/type.ts

@@ -1,7 +1,19 @@
 import { decimalPart, toFixed } from '@tremolo-ui/functions'
 
-export type MarksType = 'mark' | 'mark-number' | 'number'
-export type MarksOptions = ['step', MarksType] | [number, MarksType]
+/**
+ * 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: MarksOptions,
@@ -9,18 +21,24 @@ export function generateOptionsList(
   max: number,
   step: number,
 ) {
+  const {
+    per,
+    mark = true,
+    label = true,
+  } = typeof options === 'object' ? options : { per: options }
   const optionsList: {
     value: number
-    type: MarksType
+    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
 }

package/src/components/XYPad/Area.tsx

@@ -1,51 +1,61 @@
-import clsx from 'clsx'
-import { ComponentPropsWithoutRef, CSSProperties, ReactNode, Ref } from 'react'
+import {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  forwardRef,
+  ReactNode,
+} from 'react'
 
-import { useComposedRefs } from '../_util/composeRefs'
+import { useComposedRefs } from '../../compose-refs'
+import { cssLength } from '../_util/css-length'
+import { Placement } from '../_util/Placement'
 
 import { useXYPadContext } from './context'
 
 export interface XYPadAreaProps {
+  /** Sets `--width`; the size the theme gives it stands when omitted. */
   width?: number | string
+  /** Sets `--height`; the size the theme gives it stands when omitted. */
   height?: number | string
+  /** Sets `--color`, for the theme to colour the area with. */
   color?: string
   className?: string
   style?: CSSProperties
   /** `<XYPad.Thumb />` goes here. */
   children?: ReactNode
-  ref?: Ref<HTMLDivElement>
 }
 
-export function Area({
-  width = 120,
-  height = 120,
-  color,
-  children,
-  className,
-  style,
-  ref,
-  ...props
-}: XYPadAreaProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>) {
-  const { areaRef } = useXYPadContext()
+type Props = XYPadAreaProps &
+  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>
 
-  // 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)
+export const Area = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
+  function Area(
+    { width, height, color, children, className, style, ...props },
+    forwardedRef,
+  ) {
+    const { areaRef } = useXYPadContext()
 
-  return (
-    <div
-      ref={composedRef}
-      className={clsx('tremolo-xy-pad-area', className)}
-      style={{
-        ...{ '--color': color },
-        width: width,
-        height: height,
-        ...style,
-      }}
-      {...props}
-    >
-      {children}
-    </div>
-  )
-}
+    // 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>(forwardedRef, areaRef)
+
+    return (
+      <div
+        ref={composedRef}
+        className={className}
+        style={
+          {
+            '--color': color,
+            '--width': cssLength(width),
+            '--height': cssLength(height),
+            // The thumb inside is placed against this box.
+            position: 'relative',
+            ...style,
+          } as CSSProperties
+        }
+        {...props}
+      >
+        <Placement name="XYPad.Area">{children}</Placement>
+      </div>
+    )
+  },
+)