@tremolo-ui/react 0.7.0 → 0.8.0

package/src/components/XYPad/Area.tsx

@@ -1,56 +1,34 @@
 import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
 
 import { useComposedRefs } from '../../compose-refs'
-import { cssLength } from '../_util/css-length'
 import { Placement } from '../_util/Placement'
 
 import { useXYPadContext } from './context'
 
-import type { CSSVariables } from '../../css-variables'
-
-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
-
-  style?: CSSProperties & CSSVariables<'width' | 'height' | 'color'>
-}
-
-type Props = XYPadAreaProps &
-  Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>
-
-export const Area = /* @__PURE__ */ forwardRef<HTMLDivElement, Props>(
-  function Area(
-    { width, height, color, children, className, style, ...props },
-    forwardedRef,
-  ) {
-    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>(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>
-    )
-  },
-)
+export const Area = /* @__PURE__ */ forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<'div'>
+>(function Area({ children, className, style, ...props }, forwardedRef) {
+  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>(forwardedRef, areaRef)
+
+  return (
+    <div
+      ref={composedRef}
+      className={className}
+      style={
+        {
+          // The thumb inside is placed against this box.
+          position: 'relative',
+          ...style,
+        } as CSSProperties
+      }
+      {...props}
+    >
+      <Placement name="XYPad.Area">{children}</Placement>
+    </div>
+  )
+})

package/src/components/XYPad/Thumb.tsx

@@ -7,10 +7,12 @@ import {
   CSSProperties,
 } from 'react'
 
+import { toXY, type XYInput } from '@tremolo-ui/dom'
+
 import { useCheckPlacement } from '../_util/Placement'
 import { VisuallyHiddenRangeInput } from '../_util/VisuallyHiddenRangeInput'
 
-import { toXY, useXYPadContext, type XYInput } from './context'
+import { useXYPadContext } from './context'
 
 import type { CSSVariables } from '../../css-variables'
 

package/src/components/XYPad/context.tsx

@@ -1,12 +1,10 @@
 import { createContext, RefObject, useContext } from 'react'
 
-import { toXY, type XY, type XYInput } from '@tremolo-ui/dom'
+import { type XY } 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>

package/src/components/XYPad/index.tsx

@@ -12,26 +12,30 @@ import {
 
 import {
   applyDelta,
+  arrowKeyMove,
   type AxisOptions,
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
   InputEventOption,
   ModifierState,
   type ModifierValue,
   selectModifier,
+  toXY,
+  valuePercent,
+  wheelMove,
+  type XY,
+  type XYInput,
 } from '@tremolo-ui/dom'
-import { linearScale, type Scale, toFixed } from '@tremolo-ui/functions'
+import { linearScale, 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 {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from '../../input-event'
 
 import { Area } from './Area'
-import { toXY, XY, XYInput, XYPadProvider } from './context'
+import { XYPadProvider } from './context'
 import { Thumb, XYPadThumbMethods } from './Thumb'
 
 const defaultExternalStyles: XYPadProps['externalStyles'] = {
@@ -227,14 +231,17 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
     const scale = useMemo(() => toXY(_scale), [_scale])
     const reverse = useMemo(() => toXY(_reverse), [_reverse])
 
-    const percent = useMemo((): XY<number> => {
-      const normalized = [0, 1].map((i) =>
-        scale[i].normalize(value[i], min[i], max[i]),
-      )
-      return [0, 1].map((i) =>
-        toFixed((reverse[i] ? 1 - normalized[i] : normalized[i]) * 100),
-      ) as XY<number>
-    }, [value, min, max, scale, reverse])
+    const percent = useMemo(
+      (): XY<number> =>
+        [0, 1].map((i) =>
+          valuePercent(
+            value[i],
+            { min: min[i], max: max[i], scale: scale[i] },
+            reverse[i],
+          ),
+        ) as XY<number>,
+      [value, min, max, scale, reverse],
+    )
 
     // --- internal functions ---
     // `AxisOptions` extends `ValueRange`, so the same pair also describes the
@@ -291,21 +298,15 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
 
     const handleKeyDown = useCallback(
       (event: React.KeyboardEvent<HTMLDivElement>) => {
-        const key = event.key
-        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
+        // focus: 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 move = arrowKeyMove(event.key)
+        if (!move) return
         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))
+        const { axis: i, direction } = move
+        onChange(nudge(i, reverse[i] ? -direction : direction, keyboard, event))
       },
       [onChange, inactive, keyboard, reverse, nudge],
     )
@@ -337,19 +338,11 @@ export const Root = /* @__PURE__ */ forwardRef<XYPadMethods, Props>(
 
     const wheelRefCallback = useWheel<HTMLDivElement>((event) => {
       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
+      const move = wheelMove(event)
+      if (!move) return
       event.preventDefault()
-      let direction = 1
-      if (delta < 0) direction *= -1
-      if (reverse[i]) direction *= -1
-      onChange(nudge(i, direction, wheel, event))
+      const { axis: i, direction } = move
+      onChange(nudge(i, reverse[i] ? -direction : direction, wheel, event))
     }, WHEEL_OPTIONS)
 
     // Composed once, so React attaches the refs a single time instead of
@@ -444,10 +437,4 @@ export const XYPad = {
 }
 
 export { type XYPadThumbProps, type XYPadThumbMethods } from './Thumb'
-export { type XYPadAreaProps } from './Area'
-export {
-  useXYPadContext,
-  type XYPadContextValue,
-  type XY,
-  type XYInput,
-} from './context'
+export { useXYPadContext, type XYPadContextValue } from './context'

package/src/components/_util/VisuallyHiddenRangeInput.tsx

@@ -1,6 +1,6 @@
 import { ComponentPropsWithoutRef, forwardRef } from 'react'
 
-import { visuallyHiddenStyle } from './visually-hidden'
+import { visuallyHiddenStyle } from '@tremolo-ui/dom'
 
 type Props = Omit<ComponentPropsWithoutRef<'input'>, 'type' | 'style'>
 

package/src/hooks/_internal/useCheckSteps.ts

@@ -1,162 +1,25 @@
 import { useEffect } from 'react'
 
-import {
-  applyDelta,
-  type InputEventOption,
-  type ModifierState,
-  type ModifierValue,
-} from '@tremolo-ui/dom'
-import { linearScale, type ValueRange } from '@tremolo-ui/functions'
-
-/** Positions probed across the travel. The ends are left out so that the
- * clamp at `min` and `max` cannot be mistaken for a press that does nothing. */
-const PROBES = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
-
-const NONE: ModifierState = {
-  shiftKey: false,
-  altKey: false,
-  ctrlKey: false,
-  metaKey: false,
-}
-
-const MODIFIER_STATE: Record<string, ModifierState> = {
-  shift: { ...NONE, shiftKey: true },
-  alt: { ...NONE, altKey: true },
-  ctrl: { ...NONE, ctrlKey: true },
-  meta: { ...NONE, metaKey: true },
-}
-
-/** Each entry of a modifier-aware input option, as a name and held keys. */
-function entries(
-  options: ModifierValue<InputEventOption>,
-): { name: string; modifiers: ModifierState }[] {
-  if (Array.isArray(options)) return [{ name: '', modifiers: NONE }]
-  return Object.keys(options).map((key) => ({
-    name: key === 'default' ? '' : key,
-    modifiers: MODIFIER_STATE[key] ?? NONE,
-  }))
-}
-
-interface Outcome {
-  /** The press changed the value at least once across the travel. */
-  moved: boolean
-  /** The change reached the displayed text at least once. */
-  visible: boolean
-}
-
-/**
- * Press every entry of `options` at nine points along the travel and report
- * whether anything came of it.
- *
- * Run against `applyDelta` itself rather than against a reading of `step`:
- * the whole point is that the amount, the step and the scale interact, and
- * the pipeline is the only thing that knows how.
- */
-function probe(
-  options: ModifierValue<InputEventOption>,
-  range: ValueRange,
-  format?: (value: number) => string,
-): Outcome {
-  const { min, max, scale = linearScale } = range
-  const outcome: Outcome = { moved: false, visible: false }
-
-  for (const { modifiers } of entries(options)) {
-    for (const position of PROBES) {
-      const value = scale.denormalize(position, min, max)
-      const up = applyDelta(value, 1, options, range, modifiers)
-      const down = applyDelta(value, -1, options, range, modifiers)
-      if (up !== value || down !== value) outcome.moved = true
-      if (!format) continue
-      const shown = format(value)
-      if (format(up) !== shown || format(down) !== shown) outcome.visible = true
-    }
-  }
-
-  return outcome
-}
-
-export interface CheckStepsOptions {
-  /** The component, for the message. */
-  component: string
-  /** The axis, for a component that has more than one. */
-  axis?: string
-  /**
-   * The range to probe, or `null` to check nothing. An unbounded input has no
-   * travel to sample, so `NumberInput` passes `null` when `min` and `max` are
-   * not both there.
-   */
-  range: ValueRange | null
-  keyboard?: ModifierValue<InputEventOption> | null
-  wheel?: ModifierValue<InputEventOption> | null
-  /**
-   * How the value is displayed, where the component shows one. Called with
-   * probe values only, and only in development.
-   */
-  format?: (value: number) => string
-}
+import { checkSteps, type CheckStepsOptions } from '@tremolo-ui/dom'
 
 /**
  * Warn, in development only, when a key press or a wheel notch cannot produce
- * a change the user can see.
- *
- * Two settings that are each fine on their own can cancel out, and nothing
- * fails when they do — the control simply sits there:
- *
- * - **`step` coarser than the amount.** `keyboard={['raw', 0.1]}` with
- *   `step={1}` rounds every press straight back to where it started
- * - **the display coarser than the amount.** A `format` showing two decimals
- *   of a kHz value cannot show a press worth 1 Hz
- *
- * The second is only reported when the press is invisible at *every* point
- * along the travel. A display that rounds is a deliberate choice and is
- * normally right — it is being too coarse everywhere that makes it a mistake.
+ * a change the user can see. The probing is `checkSteps` in the core.
  *
  * @internal
  */
-export function useCheckSteps({
-  component,
-  axis,
-  range,
-  keyboard,
-  wheel,
-  format,
-}: CheckStepsOptions) {
+export function useCheckSteps(options: CheckStepsOptions) {
+  const { component, axis, range, keyboard, wheel } = options
   const { min, max, step, scale } = range ?? {}
-  const where = axis ? `${component} (${axis})` : component
 
   useEffect(() => {
     try {
       // Inline and first, so a bundler folds the comparison and drops the
-      // whole block — the probing and the message strings with it. See
-      // `useCheckPlacement` for why it cannot go through a helper, and why
-      // it is wrapped.
+      // whole block — and with it the only call to `checkSteps`, which then
+      // falls out of the bundle too. See `useCheckPlacement` for why it
+      // cannot go through a helper, and why it is wrapped.
       if (process.env.NODE_ENV === 'production') return
-      if (!range || min === undefined || max === undefined || !(min < max)) {
-        return
-      }
-
-      for (const [name, options] of [
-        ['keyboard', keyboard],
-        ['wheel', wheel],
-      ] as const) {
-        if (!options) continue
-        const { moved, visible } = probe(options, range, format)
-        if (!moved) {
-          console.warn(
-            `[tremolo-ui] ${where}: \`${name}\` cannot move the value.` +
-              (step !== undefined
-                ? ` Each press is smaller than \`step\` (${step}), so it rounds`
-                : ' Each press rounds') +
-              ' straight back to where it started.',
-          )
-        } else if (format && !visible) {
-          console.warn(
-            `[tremolo-ui] ${where}: \`${name}\` moves the value, but \`format\`` +
-              ' shows the same text before and after, everywhere in the range.' +
-              ' The display is too coarse for it to be seen.',
-          )
-        }
-      }
+      for (const warning of checkSteps(options)) console.warn(warning)
     } catch {
       // No bundler substituted NODE_ENV, so a production build cannot be told
       // from a development one. Say nothing rather than break.
@@ -165,5 +28,5 @@ export function useCheckSteps({
     // on what actually decides the outcome. `format` is left out on purpose:
     // an inline arrow function would make this run every render.
     // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [where, min, max, step, scale, keyboard, wheel])
+  }, [component, axis, min, max, step, scale, keyboard, wheel])
 }

package/src/hooks/useLongPress.ts

@@ -1,65 +1,49 @@
-import { useCallback, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 
-import { useEventListener } from './useEventListener'
-import { useInterval } from './useInterval'
+import { createLongPress, type LongPressInstance } from '@tremolo-ui/dom'
 
+import { useCallbackRef } from './_internal/useCallbackRef'
+
+/**
+ * Repeat `callback` while a pointer is held down: once on the press, then
+ * every `interval` after `initialDelay`. The repeat itself is
+ * `createLongPress` in `@tremolo-ui/dom`.
+ *
+ * Returns the function that starts a press, for an `onPointerDown`.
+ */
 export function useLongPress(
   callback: () => void,
   initialDelay = 500,
   interval = 40,
 ) {
-  const [pressed, setPressed] = useState(false)
-  const [delay, setDelay] = useState(initialDelay)
-  const activePointerId = useRef<number | null>(null)
-  const isPressed = useRef(false)
-
-  useInterval(
-    () => {
-      callback()
-      setDelay(interval)
-    },
-    pressed ? delay : null,
-  )
-
-  const stop = useCallback(
-    (pointerId?: number) => {
-      if (!isPressed.current) return
-      if (
-        pointerId !== undefined &&
-        activePointerId.current !== null &&
-        activePointerId.current !== pointerId
-      )
-        return
-
-      isPressed.current = false
-      activePointerId.current = null
-      setPressed(false)
-      setDelay(initialDelay)
-    },
-    [initialDelay],
-  )
+  // Updated before layout effects run, so that a press started from one
+  // right after a re-render already calls the new callback.
+  const onPress = useCallbackRef(callback)
+  const instanceRef = useRef<LongPressInstance | null>(null)
 
-  useEventListener(globalThis.window, 'pointerup', (event) => {
-    stop(event.pointerId)
+  useEffect(() => {
+    instanceRef.current?.update({ delay: initialDelay, interval })
   })
 
-  useEventListener(globalThis.window, 'pointercancel', (event) => {
-    stop(event.pointerId)
-  })
-
-  useEventListener(globalThis.window, 'blur', () => {
-    stop()
-  })
+  useEffect(() => {
+    const instance = createLongPress({
+      onPress: () => onPress(),
+      delay: initialDelay,
+      interval,
+    })
+    instanceRef.current = instance
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+    }
+    // Created once: the options are pushed with update() above, so that a new
+    // delay does not end a press in progress.
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
 
   return useCallback(
-    (event?: Pick<PointerEvent, 'button' | 'pointerId'>) => {
-      if (isPressed.current || (event && event.button !== 0)) return
-
-      isPressed.current = true
-      activePointerId.current = event?.pointerId ?? null
-      callback()
-      setPressed(true)
-    },
-    [callback],
+    (event?: Pick<PointerEvent, 'button' | 'pointerId'>) =>
+      instanceRef.current?.start(event),
+    [],
   )
 }

package/src/hooks/useMIDIAccess.ts

@@ -7,14 +7,6 @@ import {
   type MIDIAccessState,
 } from '@tremolo-ui/dom'
 
-export {
-  NOT_SUPPORTED,
-  PERMISSION_DENIED,
-  UNAVAILABLE,
-  type MIDIAccessError,
-  type MIDIAccessOptions,
-} from '@tremolo-ui/dom'
-
 const INITIAL_STATE: MIDIAccessState = {
   midiAccess: null,
   error: null,

package/src/hooks/useMIDIInput.ts

@@ -2,13 +2,10 @@ import { useEffect, useRef } from 'react'
 
 import {
   createMIDIInput,
-  PITCH_BEND_CENTER,
   type MIDIInputHandlers,
   type MIDIInputInstance,
 } from '@tremolo-ui/dom'
 
-export { PITCH_BEND_CENTER, type MIDIInputHandlers }
-
 /**
  * Handle MIDI input events. To be used with {@link useMIDIAccess}.
  *

package/src/index.ts

@@ -33,28 +33,23 @@ export {
 } from './components/NumberInput'
 export {
   Piano,
-  SHORTCUTS,
   type PianoProps,
   type PianoMethods,
   type KeyState,
   type KeyAttributes,
-  type KeyboardShortcuts,
 } from './components/Piano'
 export {
   PointsEditor,
   usePointsEditorContext,
-  clampPoint,
   type PointsEditorProps,
   type PointsEditorContextValue,
   type PointsEditorPointProps,
-  type PointBaseType,
 } from './components/PointsEditor'
 export {
   Slider,
   useSliderContext,
   type SliderContextValue,
   type SliderMarksOptionProps,
-  type MarksOptions,
   type SliderMarksProps,
   type SliderMethods,
   type SliderProps,
@@ -68,11 +63,8 @@ export {
   type XYPadContextValue,
   type XYPadProps,
   type XYPadMethods,
-  type XYPadAreaProps,
   type XYPadThumbProps,
   type XYPadThumbMethods,
-  type XY,
-  type XYInput,
 } from './components/XYPad'
 
 export { type CSSVariables } from './css-variables'
@@ -85,24 +77,7 @@ export { useDropZone, type UseDropZoneOptions } from './hooks/useDropZone'
 export { useEventListener } from './hooks/useEventListener'
 export { useInterval } from './hooks/useInterval'
 export { useLongPress } from './hooks/useLongPress'
-export {
-  useMIDIAccess,
-  NOT_SUPPORTED,
-  PERMISSION_DENIED,
-  UNAVAILABLE,
-  type MIDIAccessError,
-  type MIDIAccessOptions,
-} from './hooks/useMIDIAccess'
-export {
-  useMIDIInput,
-  PITCH_BEND_CENTER,
-  type MIDIInputHandlers,
-} from './hooks/useMIDIInput'
+export { useMIDIAccess } from './hooks/useMIDIAccess'
+export { useMIDIInput } from './hooks/useMIDIInput'
 export { useMIDIMessage } from './hooks/useMIDIMessage'
 export { useWheel, type UseWheelOptions } from './hooks/useWheel'
-
-export {
-  DEFAULT_DRAG_SENSITIVITY,
-  DEFAULT_KEYBOARD_OPTIONS,
-  DEFAULT_WHEEL_OPTIONS,
-} from './input-event'