@tremolo-ui/react 0.5.0 → 0.7.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,12 @@
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+
+import { visuallyHiddenStyle } from './visually-hidden'
+
+type Props = Omit<ComponentPropsWithoutRef<'input'>, 'type' | 'style'>
+
+export const VisuallyHiddenRangeInput = /* @__PURE__ */ forwardRef<
+  HTMLInputElement,
+  Props
+>((props, ref) => (
+  <input {...props} ref={ref} type="range" style={visuallyHiddenStyle} />
+))

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/decimal-digits.ts

@@ -0,0 +1,23 @@
+/**
+ * How many digits a number carries after the decimal point.
+ *
+ * `Slider.Marks` builds its labels by multiplying an interval, which leaves
+ * binary debris in the last digits (`0.1 * 3` is `0.30000000000000004`). The
+ * count is what tells `toFixed` how far to round that back.
+ *
+ * The exponent form has to be handled separately: `String(1e-7)` is `'1e-7'`,
+ * which has no decimal point at all, so reading the text after the point
+ * reports no digits and the interval rounds away to whole numbers.
+ */
+export function decimalDigits(x: number): number {
+  if (!Number.isFinite(x)) return 0
+
+  const text = String(x)
+  const e = text.indexOf('e')
+  if (e === -1) return text.split('.')[1]?.length ?? 0
+
+  const fraction = text.slice(0, e).split('.')[1]?.length ?? 0
+  // A negative exponent pushes the point further right, a positive one pulls
+  // it back past the digits that are there.
+  return Math.max(0, fraction - Number(text.slice(e + 1)))
+}

package/src/components/_util/visually-hidden.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties } from 'react'
+
+/**
+ * Take an element out of sight while leaving it in the accessibility tree and
+ * in the tab order.
+ *
+ * `display: none` and `visibility: hidden` would remove it from both, and the
+ * native control underneath a headless component is what carries the ARIA and
+ * the keyboard behaviour. `pointer-events: none` is safe because nothing is
+ * ever clicked here directly: a `<label>` forwards its click, and a drag is
+ * handled by the part that is visible.
+ */
+export const visuallyHiddenStyle: 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',
+}

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/css-variables.ts

@@ -0,0 +1,23 @@
+/**
+ * CSS custom properties, for a `style` object.
+ *
+ * React's `CSSProperties` has no key starting with `--`, so
+ * `style={{ '--color': 'red' }}` is refused as an unknown property even though
+ * the browser takes it. Every part accepts this alongside `CSSProperties`,
+ * which is how a variable the component or a theme reads is set inline.
+ *
+ * `T` names the custom properties the part itself writes or reads, without the
+ * leading `--`, so that an editor can suggest them. Any other `--` name is
+ * still accepted — a theme reads variables of its own, such as the colours of
+ * each kind of key.
+ *
+ * @example
+ * CSSVariables<'thickness' | 'length'>
+ * // { '--thickness'?: string | number, '--length'?: string | number,
+ * //   [name: `--${string}`]: string | number | undefined }
+ */
+export type CSSVariables<T extends string = never> = {
+  [K in T as `--${K}`]?: string | number
+} & {
+  [K in `--${string}`]?: string | number
+}

package/src/hooks/_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,169 @@
+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
+}
+
+/**
+ * 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,22 +1,50 @@
 import { useEffect, useState } from 'react'
 
-import { createDrag } from '@tremolo-ui/dom'
+import { createDrag, type DragState } from '@tremolo-ui/dom'
 
 import { useCallbackRef } from './_internal/useCallbackRef'
 
-interface UseDragProps {
+export interface UseDragOptions {
   /**
-   * Threshold at which the onDrag event fires.
-   * Prevents onDrag events from firing, for example, when double-clicking.
+   * Pixels the pointer has to travel before the drag counts as one.
+   *
+   * A click moves the pointer by a pixel or two, so without a threshold a
+   * double click reports a drag between the two presses.
+   *
+   * @default 1
    */
   threshold?: number
 
   /** 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
+
+  /**
+   * Called on every move once the drag has started, with the pointer position
+   * relative to the element and how far it moved since the last call.
+   *
+   * @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
+  /** Called once the pointer has moved past `threshold`, not on pointerdown. */
+  onDragStart?: (state: DragState) => void
+  /** Called when the pointer is released, only if the drag ever started. */
+  onDragEnd?: (state: DragState) => void
 }
 
 /**
@@ -27,10 +55,11 @@ interface UseDragProps {
 export function useDrag<T extends Element>({
   threshold = 1,
   cursor,
+  pointerLock,
   onDrag,
   onDragStart,
   onDragEnd,
-}: UseDragProps): (node: T | null) => void {
+}: UseDragOptions): (node: T | null) => void {
   const dragHandler = useCallbackRef(onDrag)
   const dragStartHandler = useCallbackRef(onDragStart)
   const dragEndHandler = useCallbackRef(onDragEnd)
@@ -46,13 +75,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

@@ -5,6 +5,7 @@ import {
   elementMapping,
   relativeMapping,
   type AxisOptions,
+  type DragState,
   type DragValueInstance,
   type XY,
   type XYInput,
@@ -36,17 +37,65 @@ export interface UseDragValueOptions {
    * @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 */
+  /**
+   * Move the value on pointerdown, before the pointer has moved at all. With
+   * `baseElementRef` that makes a press jump the value to where it landed.
+   *
+   * @see DragValueOptions.updateOnPointerDown
+   */
   updateOnPointerDown?: boolean
-  /** @default 0 */
+  /**
+   * Pixels the pointer has to travel before the drag counts as one. The
+   * default is 0, so the value follows the very first move.
+   *
+   * @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
 
-  onChange?: (value: XY<number>) => void
-  onDragStart?: (value: XY<number>) => void
-  onDragEnd?: (value: XY<number>) => void
+  /**
+   * Called with the new value whenever the drag moves it. The hook holds no
+   * value of its own, so this is where it is stored.
+   *
+   * @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
+  /** Called once the drag starts, with the value it starts from. */
+  onDragStart?: (value: XY<number>, state: DragState) => void
+  /** Called when the pointer is released, with the value it ends on. */
+  onDragEnd?: (value: XY<number>, state: DragState) => void
 }
 
 /**
@@ -64,6 +113,7 @@ export function useDragValue<T extends Element>(
     updateOnPointerDown,
     threshold,
     cursor,
+    pointerLock,
   } = options
 
   if (!baseElementRef && !options.getValue) {
@@ -98,22 +148,31 @@ export function useDragValue<T extends Element>(
     const instance = createDragValue(node, {
       axis: latest.current.axis,
       mapping: baseElementRef
-        ? elementMapping(() => baseElementRef.current)
+        ? 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,
-      onChange: (value) => changeHandler(value),
-      onDragStart: (value) => {
+      pointerLock: latest.current.pointerLock,
+      shouldStart: (event) => latest.current.shouldStart?.(event) ?? true,
+      onChange: (value, state) => changeHandler(value, state),
+      onDragStart: (value, state) => {
         setDragging(true)
-        dragStartHandler(value)
+        dragStartHandler(value, state)
       },
-      onDragEnd: (value) => {
+      onDragEnd: (value, state) => {
         setDragging(false)
-        dragEndHandler(value)
+        dragEndHandler(value, state)
       },
     })
     instanceRef.current = instance
@@ -142,6 +201,7 @@ export function useDragValue<T extends Element>(
       updateOnPointerDown,
       threshold,
       cursor,
+      pointerLock,
     })
   })