@tremolo-ui/react 0.4.0 → 0.6.0

package/src/components/_util/Placement.tsx

@@ -0,0 +1,68 @@
+import { createContext, ReactNode, useContext, useEffect } from 'react'
+
+/**
+ * The subcomponent that established the current placement, if any.
+ *
+ * @internal
+ */
+const PlacementContext = /* @__PURE__ */ createContext<string | null>(null)
+
+/**
+ * Marks its children as being inside `name`, for {@link useCheckPlacement}.
+ *
+ * @internal
+ */
+export function Placement({
+  name,
+  children,
+}: {
+  name: string
+  children: ReactNode
+}) {
+  return (
+    <PlacementContext.Provider value={name}>
+      {children}
+    </PlacementContext.Provider>
+  )
+}
+
+/**
+ * Warn, in development only, when `child` is not rendered inside `parent`.
+ *
+ * A compound component renders its children exactly as they are composed, so a
+ * subcomponent put at the wrong level still renders — it only loses whatever
+ * its layout depended on, and does so silently. `Slider.Thumb` outside
+ * `Slider.Track` keeps its `position: absolute` but resolves it against the
+ * page rather than the track, and neither the build nor the tests notice.
+ *
+ * @internal
+ */
+export function useCheckPlacement(child: string, parent: string) {
+  const found = useContext(PlacementContext)
+
+  useEffect(() => {
+    try {
+      // `process.env.NODE_ENV` is written out here, inline and first, so that a
+      // bundler substituting it folds the comparison and drops this whole
+      // block — the message strings with it. Reading the flag through a helper
+      // or a module constant leaves the branch in the bundle instead: neither
+      // folds, which was measured with esbuild rather than assumed.
+      //
+      // The read is wrapped because `process` may not exist at all. The
+      // package is built with `platform: 'neutral'`, so a page loading the ESM
+      // straight from a CDN has no bundler to substitute it, and a bare
+      // reference would throw a `ReferenceError` mid-effect.
+      if (process.env.NODE_ENV !== 'production' && found !== parent) {
+        console.warn(
+          `[tremolo-ui] ${child} has to be rendered inside ${parent}` +
+            (found === null ? '.' : `, but it is inside ${found}.`) +
+            ' It renders either way, so nothing fails — its position just' +
+            ' comes out wrong.',
+        )
+      }
+    } catch {
+      // No bundler substituted NODE_ENV, so there is no way to tell a
+      // production build from a development one. Say nothing rather than break.
+    }
+  }, [found, child, parent])
+}

package/src/components/_util/VisuallyHiddenRangeInput.tsx

@@ -0,0 +1,24 @@
+import { ComponentPropsWithoutRef, CSSProperties, forwardRef } from 'react'
+
+const hiddenStyle: CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  clipPath: 'inset(50%)',
+  whiteSpace: 'nowrap',
+  border: 0,
+  pointerEvents: 'none',
+}
+
+type Props = Omit<ComponentPropsWithoutRef<'input'>, 'type' | 'style'>
+
+export const VisuallyHiddenRangeInput = /* @__PURE__ */ forwardRef<
+  HTMLInputElement,
+  Props
+>((props, ref) => (
+  <input {...props} ref={ref} type="range" style={hiddenStyle} />
+))

package/src/components/_util/css-length.ts

@@ -0,0 +1,13 @@
+/**
+ * A number as a CSS length, for a custom property.
+ *
+ * React appends `px` to a bare number for the properties it knows take a
+ * length, and a custom property is never one of them: `--size: 50` would come
+ * out as the invalid `50`. Anything already a string is passed through, so
+ * `'3rem'` and `'100%'` still work.
+ */
+export function cssLength(
+  value: number | string | undefined,
+): string | undefined {
+  return typeof value === 'number' ? `${value}px` : value
+}

package/src/{components/_util/composeRefs.tsx → compose-refs/index.tsx}

@@ -1,5 +1,31 @@
-// ref:
-// https://github.com/radix-ui/primitives/blob/2bab24a811e45c7a83198659272097f6cfa5a165/packages/react/compose-refs/src/compose-refs.tsx
+/**
+ * MIT License
+ *
+ * Copyright (c) 2022 WorkOS
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ *
+ * Copied from Radix UI Primitives.
+ * The source is here.
+ * https://github.com/radix-ui/primitives/blob/2bab24a811e45c7a83198659272097f6cfa5a165/packages/react/compose-refs/src/compose-refs.tsx
+ */
 
 import { useCallback } from 'react'
 
@@ -26,7 +52,7 @@ function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
     let hasCleanup = false
     const cleanups = refs.map((ref) => {
       const cleanup = setRef(ref, node)
-      if (!hasCleanup && typeof cleanup == 'function') {
+      if (!hasCleanup && typeof cleanup === 'function') {
         hasCleanup = true
       }
       return cleanup
@@ -40,7 +66,7 @@ function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
       return () => {
         for (let i = 0; i < cleanups.length; i++) {
           const cleanup = cleanups[i]
-          if (typeof cleanup == 'function') {
+          if (typeof cleanup === 'function') {
             cleanup()
           } else {
             setRef(refs[i], null)
@@ -56,7 +82,9 @@ function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
  * Accepts callback refs and RefObject(s)
  */
 function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+  // The ref list is variadic, so neither the callback nor its dependencies can
+  // be written as the literals the compiler rules expect.
+  // oxlint-disable-next-line react-hooks/exhaustive-deps, react/use-memo
   return useCallback(composeRefs(...refs), refs)
 }
 

package/src/hooks/{useCallbackRef.ts → _internal/useCallbackRef.ts}

@@ -16,6 +16,8 @@ export function useCallbackRef<Args extends unknown[], Return>(
     callbackRef.current = callback
   })
 
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+  // `deps` comes from the caller, so it cannot be the array literal the
+  // compiler rules expect.
+  // oxlint-disable-next-line react-hooks/exhaustive-deps, react/use-memo
   return useCallback((...args: Args) => callbackRef.current?.(...args), deps)
 }

package/src/hooks/_internal/useCheckSteps.ts

@@ -0,0 +1,170 @@
+import { useEffect } from 'react'
+
+import {
+  applyDelta,
+  linearScale,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  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
+}
+
+/**
+ * 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.
+ *
+ * @internal
+ */
+export function useCheckSteps({
+  component,
+  axis,
+  range,
+  keyboard,
+  wheel,
+  format,
+}: CheckStepsOptions) {
+  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.
+      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.',
+          )
+        }
+      }
+    } catch {
+      // No bundler substituted NODE_ENV, so a production build cannot be told
+      // from a development one. Say nothing rather than break.
+    }
+    // `range` and `format` are rebuilt on most renders, so the effect is keyed
+    // 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])
+}

package/src/hooks/useAnimationFrame.ts

@@ -1,18 +1,28 @@
-import { DependencyList, useCallback, useEffect, useRef } from 'react'
+import { DependencyList, useEffect, useRef } from 'react'
+
+import { useCallbackRef } from './_internal/useCallbackRef'
 
 export function useAnimationFrame(
   callback = () => {},
   deps: DependencyList = [],
 ) {
   const reqIdRef = useRef(-1)
-  const loop = useCallback(() => {
-    reqIdRef.current = requestAnimationFrame(loop)
-    callback()
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [callback, ...deps])
+  // Read through a ref rather than depended on: `useAnimationFrame(() => ...)`
+  // is a new function on every render, and a callback that renders would then
+  // cancel and re-schedule its own loop on every frame. What restarts the loop
+  // is the caller's `deps`, and nothing else.
+  const runCallback = useCallbackRef(callback)
 
   useEffect(() => {
+    // Kept inside the effect: as a `useCallback` the loop would have to
+    // reference itself before it is declared, which the compiler rules reject.
+    const loop = () => {
+      reqIdRef.current = requestAnimationFrame(loop)
+      runCallback()
+    }
+
     reqIdRef.current = requestAnimationFrame(loop)
     return () => cancelAnimationFrame(reqIdRef.current)
-  }, [loop])
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+  }, [runCallback, ...deps])
 }

package/src/hooks/useDrag.ts

@@ -1,8 +1,8 @@
 import { useEffect, useState } from 'react'
 
-import { createDrag } from '@tremolo-ui/dom'
+import { createDrag, type DragState } from '@tremolo-ui/dom'
 
-import { useCallbackRef } from './useCallbackRef'
+import { useCallbackRef } from './_internal/useCallbackRef'
 
 interface UseDragProps {
   /**
@@ -14,9 +14,28 @@ interface UseDragProps {
   /** CSS cursor to show while dragging. Applied to the element itself. */
   cursor?: string
 
-  onDrag?: (x: number, y: number, deltaX: number, deltaY: number) => void
-  onDragStart?: () => void
-  onDragEnd?: () => void
+  /**
+   * Hide the pointer and read its movement directly, instead of following it
+   * around the screen.
+   *
+   * @see DragOptions.pointerLock
+   * @default false
+   */
+  pointerLock?: boolean
+
+  /**
+   * @param state the whole drag, for anything the four numbers leave out —
+   * the pointer event and its modifier keys, most of all.
+   */
+  onDrag?: (
+    x: number,
+    y: number,
+    deltaX: number,
+    deltaY: number,
+    state: DragState,
+  ) => void
+  onDragStart?: (state: DragState) => void
+  onDragEnd?: (state: DragState) => void
 }
 
 /**
@@ -27,6 +46,7 @@ interface UseDragProps {
 export function useDrag<T extends Element>({
   threshold = 1,
   cursor,
+  pointerLock,
   onDrag,
   onDragStart,
   onDragEnd,
@@ -46,13 +66,23 @@ export function useDrag<T extends Element>({
     const instance = createDrag(node, {
       threshold,
       cursor,
-      onDragStart: () => dragStartHandler(),
-      onDrag: ({ x, y, deltaX, deltaY }) => dragHandler(x, y, deltaX, deltaY),
-      onDragEnd: () => dragEndHandler(),
+      pointerLock,
+      onDragStart: (state) => dragStartHandler(state),
+      onDrag: (state) =>
+        dragHandler(state.x, state.y, state.deltaX, state.deltaY, state),
+      onDragEnd: (state) => dragEndHandler(state),
     })
 
     return () => instance.destroy()
-  }, [node, threshold, cursor, dragHandler, dragStartHandler, dragEndHandler])
+  }, [
+    node,
+    threshold,
+    cursor,
+    pointerLock,
+    dragHandler,
+    dragStartHandler,
+    dragEndHandler,
+  ])
 
   return setNode
 }

package/src/hooks/useDragValue.ts

@@ -0,0 +1,194 @@
+import { RefObject, useEffect, useRef, useState } from 'react'
+
+import {
+  createDragValue,
+  elementMapping,
+  relativeMapping,
+  type AxisOptions,
+  type DragState,
+  type DragValueInstance,
+  type XY,
+  type XYInput,
+} from '@tremolo-ui/dom'
+
+import { useCallbackRef } from './_internal/useCallbackRef'
+
+export interface UseDragValueOptions {
+  /** Scaling of each axis; a single value applies to both. */
+  axis: XYInput<AxisOptions>
+
+  /**
+   * Normalize the pointer against the bounding rect of this element, so that
+   * the value *is* the position pointed at.
+   *
+   * Give either this or `getValue`.
+   */
+  baseElementRef?: RefObject<Element | null>
+
+  /**
+   * Move the value away from where it stood when the drag started, by the
+   * distance dragged. The pointer position itself carries no meaning.
+   *
+   * Give either this or `baseElementRef`.
+   */
+  getValue?: () => XY<number>
+  /**
+   * Pixels of movement that span the whole range, with `getValue`.
+   * @default 100
+   */
+  pixelRange?: XYInput<number>
+  /**
+   * How much the movement counts, read on every move. `0.1` makes the same
+   * movement cover a tenth of the range, which is what a fine-adjustment
+   * modifier wants.
+   *
+   * With `baseElementRef` the value is normally the position pointed at, so
+   * anything but `1` turns the mapping relative and leaves the pointer and the
+   * value apart for the rest of the drag.
+   *
+   * @see relativeMapping
+   * @see elementMapping
+   */
+  sensitivity?: (state: DragState) => number
+
+  /** @see DragValueOptions.updateOnPointerDown */
+  updateOnPointerDown?: boolean
+  /** @default 0 */
+  threshold?: number
+  /** CSS cursor to show while dragging. Applied to the element itself. */
+  cursor?: string
+  /**
+   * Hide the pointer and read its movement directly, instead of following it
+   * around the screen. Only with `getValue`: there is no pointer position to
+   * normalize against a `baseElementRef` while the pointer is locked.
+   *
+   * @see DragOptions.pointerLock
+   * @default false
+   */
+  pointerLock?: boolean
+  /**
+   * Decide whether a pointerdown starts a drag at all, before the pointer is
+   * captured.
+   *
+   * @see DragOptions.shouldStart
+   */
+  shouldStart?: (event: PointerEvent) => boolean
+
+  /**
+   * @param state the whole drag, for anything the value leaves out — the
+   * pointer event and its modifier keys, most of all.
+   */
+  onChange?: (value: XY<number>, state: DragState) => void
+  onDragStart?: (value: XY<number>, state: DragState) => void
+  onDragEnd?: (value: XY<number>, state: DragState) => void
+}
+
+/**
+ * Drive a value with a pointer drag.
+ *
+ * @returns a ref callback for the element that starts the drag, and whether a drag is in progress
+ */
+export function useDragValue<T extends Element>(
+  options: UseDragValueOptions,
+): { refCallback: (node: T | null) => void; dragging: boolean } {
+  const {
+    axis,
+    baseElementRef,
+    pixelRange,
+    updateOnPointerDown,
+    threshold,
+    cursor,
+    pointerLock,
+  } = options
+
+  if (!baseElementRef && !options.getValue) {
+    throw new Error(
+      'useDragValue: give either baseElementRef or getValue, so that the drag has something to move',
+    )
+  }
+
+  const [dragging, setDragging] = useState(false)
+
+  const valueGetter = useCallbackRef(options.getValue)
+  const changeHandler = useCallbackRef(options.onChange)
+  const dragStartHandler = useCallbackRef(options.onDragStart)
+  const dragEndHandler = useCallbackRef(options.onDragEnd)
+
+  // Read when the instance is created. The effect below keeps it current, and
+  // runs right after, so a stale setting is replaced within the same commit.
+  const latest = useRef(options)
+
+  const instanceRef = useRef<DragValueInstance | null>(null)
+
+  // See useDrag for why the node is held in state.
+  const [node, setNode] = useState<T | null>(null)
+
+  const [pixelRangeX, pixelRangeY] = Array.isArray(pixelRange)
+    ? pixelRange
+    : [pixelRange, pixelRange]
+
+  useEffect(() => {
+    if (!node) return
+
+    const instance = createDragValue(node, {
+      axis: latest.current.axis,
+      mapping: baseElementRef
+        ? elementMapping(() => baseElementRef.current, {
+            // Read through the ref so that a changed setting reaches a drag
+            // already in progress.
+            sensitivity: (state) => latest.current.sensitivity?.(state) ?? 1,
+          })
+        : relativeMapping({
+            pixelRange: [pixelRangeX ?? 100, pixelRangeY ?? 100],
+            // Read through the ref so that a changed setting reaches a drag
+            // already in progress.
+            sensitivity: (state) => latest.current.sensitivity?.(state) ?? 1,
+          }),
+      getValue: () => valueGetter() ?? [0, 0],
+      updateOnPointerDown: latest.current.updateOnPointerDown,
+      threshold: latest.current.threshold,
+      cursor: latest.current.cursor,
+      pointerLock: latest.current.pointerLock,
+      shouldStart: (event) => latest.current.shouldStart?.(event) ?? true,
+      onChange: (value, state) => changeHandler(value, state),
+      onDragStart: (value, state) => {
+        setDragging(true)
+        dragStartHandler(value, state)
+      },
+      onDragEnd: (value, state) => {
+        setDragging(false)
+        dragEndHandler(value, state)
+      },
+    })
+    instanceRef.current = instance
+
+    return () => {
+      instanceRef.current = null
+      instance.destroy()
+    }
+  }, [
+    node,
+    baseElementRef,
+    pixelRangeX,
+    pixelRangeY,
+    valueGetter,
+    changeHandler,
+    dragStartHandler,
+    dragEndHandler,
+  ])
+
+  // Runs after every render: the settings come from props and are cheap to
+  // push, and updating in place leaves a drag in progress untouched.
+  useEffect(() => {
+    latest.current = options
+    instanceRef.current?.update({
+      axis,
+      updateOnPointerDown,
+      threshold,
+      cursor,
+      pointerLock,
+    })
+  })
+
+  return { refCallback: setNode, dragging }
+}