@tremolo-ui/react 0.5.0 → 0.6.0

package/src/components/Knob/index.tsx

@@ -1,6 +1,6 @@
-import clsx from 'clsx'
 import {
   ComponentPropsWithoutRef,
+  CSSProperties,
   forwardRef,
   ReactNode,
   useCallback,
@@ -12,16 +12,24 @@ import {
 import type { AxisOptions, XY } from '@tremolo-ui/dom'
 import {
   applyDelta,
-  InputEventOption,
+  type InputEventOption,
+  type ModifierValue,
+  selectModifier,
   linearScale,
   type Scale,
   type ValueRange,
 } 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 { cssLength } from '../_util/css-length'
 
 import { ActiveLine } from './ActiveLine'
 import { calcAngles, KnobProvider } from './context'
@@ -30,17 +38,23 @@ import { SVGRoot } from './SVGRoot'
 import { Thumb } from './Thumb'
 
 const defaultExternalStyles: KnobProps['externalStyles'] = {
-  userSelectNone: true,
   cursor: 'grabbing',
 }
 
 export interface KnobProps {
-  // required
+  /** The current value. The knob shows only this, so update it from `onChange`. */
   value: number
+  /** The value with the knob turned all the way down. */
   min: number
+  /** The value with the knob turned all the way up. */
   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.
@@ -53,52 +67,123 @@ export interface KnobProps {
    */
   scale?: Scale
   /**
-   * value set when double-clicking
-   * restriction: enableDoubleClickDefault = true
+   * The value a double click restores, while `enableDoubleClickDefault` is on.
    * @default min
-   * @see enableDoubleClickDefault
    */
   defaultValue?: number
 
   /**
-   * Value to be used as the starting point of the line when drawing.
+   * Where the active arc starts. Put it at the centre of a bipolar control,
+   * such as a pan knob, so that the arc grows from there either way.
    * @default min
    */
   startValue?: number
 
-  /** width and height */
   /**
-   * Width and height of the knob.
-   * Defaults to the `--knob-size` CSS variable (50px).
+   * Width and height of the knob. Sets `--knob-size`; the size the theme
+   * gives it stands when this is omitted.
    */
   size?: number | string
 
   /**
-   * Global style to apply when dragged
-   * @default defaultExternalStyles
+   * The cursor to show while dragging. It is set on the dragged element, so it
+   * stays while the pointer is outside the knob.
+   *
+   * @default { cursor: 'grabbing' }
    */
   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 knob 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?: ModifierValue<InputEventOption> | null
+  /**
+   * How much a drag moves the value, per modifier key.
+   *
+   * `1` is the normal travel of 100px for the whole range; `0.1` makes the
+   * same movement cover a tenth of it. 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. It takes
+   * effect on the next movement, since a key on its own produces no pointer
+   * event.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  dragSensitivity?: ModifierValue<number>
+
+  /**
+   * Hide the cursor while dragging and read the pointer movement directly,
+   * rather than letting it wander off across the screen.
+   *
+   * A knob does not care where the pointer is, only how far it moved, and
+   * letting it wander costs twice: the cursor ends up far from the knob it is
+   * holding, and **the drag stops at the edge of the screen**, where the
+   * operating system pins the pointer and the coordinates stop changing. A
+   * `dragSensitivity` below 1 reaches that edge quickly.
+   *
+   * Off by default because it is not free: the browser shows its own notice,
+   * Esc takes the lock back, and the request needs a user gesture and can be
+   * refused. A refused request is not an error — the drag simply carries on as
+   * an ordinary one.
+   *
+   * @default false
+   */
+  pointerLock?: boolean
+
+  /**
+   * 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] }
    */
-  wheel?: InputEventOption | null
+  keyboard?: ModifierValue<InputEventOption> | null
   /**
-   * keyboard control option
-   * If null, no event will be triggered
+   * Restore `defaultValue` on a double click.
+   * @default true
    */
-  keyboard?: InputEventOption | null
   enableDoubleClickDefault?: boolean
 
+  /**
+   * Make the knob unchangeable and remove it from the tab order.
+   * The parts carry `data-disabled` while it is set.
+   */
   disabled?: boolean
+  /**
+   * Make the knob unchangeable while leaving it focusable.
+   * The parts carry `data-readonly` while it is set.
+   */
   readonly?: boolean
 
-  /** angle range [degree] */
+  /**
+   * How far the knob turns from `min` to `max`, in degrees, centred on the
+   * top.
+   * @default 270
+   */
   angleRange?: number
 
+  /**
+   * Called with the new value when a drag, the wheel, an arrow key or a double
+   * click moves it.
+   */
   onChange?: (value: number) => void
 
   /**
@@ -130,7 +215,7 @@ type Props = KnobProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KnobProps>
  */
 const WHEEL_OPTIONS = { requireFocus: true }
 
-export const Root = forwardRef<KnobMethods, Props>(
+export const Root = /* @__PURE__ */ forwardRef<KnobMethods, Props>(
   (
     {
       value,
@@ -142,8 +227,10 @@ export const Root = forwardRef<KnobMethods, Props>(
       startValue = min,
       size,
       externalStyles: _externalStyles,
-      wheel = ['raw', 1],
-      keyboard = ['raw', 1],
+      wheel = DEFAULT_WHEEL_OPTIONS,
+      keyboard = DEFAULT_KEYBOARD_OPTIONS,
+      dragSensitivity = DEFAULT_DRAG_SENSITIVITY,
+      pointerLock = false,
       enableDoubleClickDefault = true,
       disabled = false,
       readonly = false,
@@ -162,6 +249,7 @@ export const Root = forwardRef<KnobMethods, Props>(
     const elmRef = useRef<HTMLElement | SVGElement>(null)
 
     const externalStyles = { ...defaultExternalStyles, ..._externalStyles }
+    const inactive = disabled || readonly
 
     // --- internal functions ---
     const range: ValueRange = useMemo(
@@ -169,17 +257,19 @@ export const Root = forwardRef<KnobMethods, Props>(
       [min, max, step, scale],
     )
 
+    useCheckSteps({ component: 'Knob', range, keyboard, wheel })
+
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLOrSVGElement>) => {
-        if (!keyboard || !onChange || readonly) return
+        if (!keyboard || !onChange || inactive) return
         const key = event.key
         if (['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown'].includes(key)) {
           event.preventDefault()
-          const direction = key == 'ArrowRight' || key == 'ArrowUp' ? 1 : -1
-          onChange(applyDelta(value, direction, keyboard, range))
+          const direction = key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
+          onChange(applyDelta(value, direction, keyboard, range, event))
         }
       },
-      [keyboard, onChange, readonly, value, range],
+      [keyboard, onChange, inactive, value, range],
     )
 
     // --- hooks ---
@@ -197,25 +287,23 @@ export const Root = forwardRef<KnobMethods, Props>(
     >({
       axis,
       getValue: () => [value, value],
+      sensitivity: (state) =>
+        selectModifier(dragSensitivity, state.event).value,
       threshold: 1,
-      cursor: readonly ? undefined : externalStyles.cursor,
+      cursor: inactive ? undefined : externalStyles.cursor,
+      pointerLock: inactive ? false : pointerLock,
+      shouldStart: () => !inactive,
       onChange: (v) => {
-        if (readonly) return
+        if (inactive) return
         onChange?.(v[1])
       },
-      onDragStart: () => {
-        if (externalStyles.userSelectNone) addUserSelectNone()
-      },
-      onDragEnd: () => {
-        if (externalStyles.userSelectNone) removeUserSelectNone()
-      },
     })
 
     const wheelRefCallback = useWheel<HTMLElement>((event) => {
-      if (!wheel || readonly) return
+      if (!wheel || inactive) return
       event.preventDefault()
-      if (!onChange || event.deltaY == 0) return
-      onChange(applyDelta(value, -Math.sign(event.deltaY), wheel, range))
+      if (!onChange || event.deltaY === 0) return
+      onChange(applyDelta(value, -Math.sign(event.deltaY), wheel, range, event))
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
@@ -234,35 +322,38 @@ export const Root = forwardRef<KnobMethods, Props>(
     useImperativeHandle(forwardedRef, () => {
       return {
         focus() {
-          elmRef.current?.focus()
+          if (!disabled) elmRef.current?.focus()
         },
         blur() {
           elmRef.current?.blur()
         },
       }
-    }, [])
+    }, [disabled])
 
     return (
       <KnobProvider value={context}>
         <div
           ref={rootRefCallback}
-          className={clsx('tremolo-knob', className)}
-          tabIndex={0}
+          className={className}
+          tabIndex={disabled ? -1 : 0}
           role="slider"
           aria-valuenow={value}
           aria-valuemin={min}
           aria-valuemax={max}
           aria-disabled={disabled}
           aria-readonly={readonly}
-          data-dragging={dragging}
-          style={{
-            width: size,
-            height: size,
-            ...style,
-          }}
+          data-disabled={disabled ? '' : undefined}
+          data-readonly={readonly ? '' : undefined}
+          data-dragging={dragging ? '' : undefined}
+          style={
+            {
+              '--knob-size': cssLength(size),
+              ...style,
+            } as CSSProperties
+          }
           onPointerDown={onPointerDown}
           onDoubleClick={(event) => {
-            if (enableDoubleClickDefault && onChange) {
+            if (!inactive && enableDoubleClickDefault && onChange) {
               onChange(defaultValue)
             }
             onDoubleClick?.(event)
@@ -291,4 +382,6 @@ export const Knob = {
   Thumb,
 }
 
-export { useKnobContext } from './context'
+export { useKnobContext, type KnobContextValue } from './context'
+export { type KnobSVGRootProps } from './SVGRoot'
+export { type KnobThumbProps } from './Thumb'

package/src/components/NumberInput/DecrementStepper.tsx

@@ -4,14 +4,18 @@ import {
   StepperArrow,
   StepperButton,
   StepperButtonProps,
-} from './stepperButton'
+} from './StepperButton'
 
-export type DecrementStepperProps = StepperButtonProps
+// An interface rather than an alias; see `NumberInputIncrementStepperProps`.
+export interface NumberInputDecrementStepperProps extends StepperButtonProps {}
 
 /** Lowers the value by one `step`, repeating while held. */
 export function DecrementStepper(
-  props: DecrementStepperProps &
-    Omit<ComponentPropsWithoutRef<'div'>, keyof DecrementStepperProps>,
+  props: NumberInputDecrementStepperProps &
+    Omit<
+      ComponentPropsWithoutRef<'div'>,
+      keyof NumberInputDecrementStepperProps
+    >,
 ) {
   return (
     <StepperButton

package/src/components/NumberInput/IncrementStepper.tsx

@@ -4,14 +4,19 @@ import {
   StepperArrow,
   StepperButton,
   StepperButtonProps,
-} from './stepperButton'
+} from './StepperButton'
 
-export type IncrementStepperProps = StepperButtonProps
+// An interface rather than an alias, so that typedoc lists the props: the
+// shared `StepperButtonProps` is not exported for it to follow.
+export interface NumberInputIncrementStepperProps extends StepperButtonProps {}
 
 /** Raises the value by one `step`, repeating while held. */
 export function IncrementStepper(
-  props: IncrementStepperProps &
-    Omit<ComponentPropsWithoutRef<'div'>, keyof IncrementStepperProps>,
+  props: NumberInputIncrementStepperProps &
+    Omit<
+      ComponentPropsWithoutRef<'div'>,
+      keyof NumberInputIncrementStepperProps
+    >,
 ) {
   return (
     <StepperButton