useSpring

1"use client"
2 
3import * as React from "react"
4 
5export interface SpringOptions {
6  /**
7   * Seconds to settle, roughly. A spring has no fixed end, but this is the
8   * number you would have reached for with a duration.
9   */
10  duration?: number
11  /**
12   * Overshoot. `0` arrives and stops, above `0` passes the target and comes
13   * back, below `0` eases in slow. Keep it under `0.3` for anything that is
14   * not meant to be playful.
15   */
16  bounce?: number
17  /** Below this, in target units, the spring is called finished. */
18  epsilon?: number
19}
20 
21type Values = Record<string, number>
22 
23/** Fixed step, so the motion is the same on a 60Hz screen and a 120Hz one. */
24const STEP = 1 / 240
25/** A tab left in the background hands back one enormous frame. Ignore it. */
26const MAX_FRAME = 0.064
27 
28/**
29 * Apple's parameterisation: say how long and how bouncy, rather than picking
30 * mass, stiffness and damping and discovering what they add up to.
31 */
32function coefficients({ duration = 0.4, bounce = 0 }: SpringOptions) {
33  const omega = (2 * Math.PI) / duration
34  const damping =
35    bounce >= 0
36      ? (4 * Math.PI * (1 - bounce)) / duration
37      : (4 * Math.PI) / (duration * (1 + bounce))
38 
39  return { stiffness: omega * omega, damping }
40}
41 
42/**
43 * A spring over a set of named numbers, driven straight onto a callback rather
44 * than through state. A frame that re-renders is a frame that can drop.
45 *
46 * The point of a spring over a curve is interruption. A CSS animation retargeted
47 * halfway through restarts from a standstill, which is the moment it stops
48 * feeling physical. This carries velocity across every retarget, so a value
49 * already travelling keeps travelling.
50 */
51export function useSpring(
52  onFrame: (values: Values) => void,
53  options: SpringOptions = {}
54) {
55  const { epsilon = 0.0005 } = options
56  const { stiffness, damping } = coefficients(options)
57 
58  const current = React.useRef<Values>({})
59  const velocity = React.useRef<Values>({})
60  const target = React.useRef<Values>({})
61  const frame = React.useRef(0)
62  const clock = React.useRef(0)
63 
64  // Read through refs so the loop never closes over a stale callback and never
65  // has to be torn down and rebuilt when one changes.
66  const frameRef = React.useRef(onFrame)
67  const springRef = React.useRef({ stiffness, damping, epsilon })
68  React.useEffect(() => {
69    frameRef.current = onFrame
70    springRef.current = { stiffness, damping, epsilon }
71  })
72 
73  const stop = React.useCallback(() => {
74// … truncated