feat: replace "config.speed" with "config.frequency + config.damping"

Author: aleclarson

packages/core/src/SpringValue.ts

@@ -456,12 +456,12 @@ export class SpringValue<T = any> extends AnimationValue<T> {
         anim.config = config = { ...BASE_CONFIG, ...config }
       }
 
-      // When "speed" is provided, we derive "tension" and "friction" from it.
-      if (!is.und(config.speed)) {
-        config.tension = Math.pow((2 * Math.PI) / config.speed, 2) * config.mass
-        // Note: We treat "friction" as the *damping ratio* instead of as its coefficient.
+      // Derive "tension" and "friction" from "frequency" and "damping".
+      if (!is.und(config.frequency)) {
+        const damping = is.und(config.damping) ? 1 : config.damping
+        config.tension = Math.pow(config.frequency, 2) * config.mass
         config.friction =
-          (4 * Math.PI * config.friction * config.mass) / config.speed
+          (damping * Math.sqrt(config.tension * config.mass)) / 0.5
       }
 
       // Cache the angular frequency in rad/ms

packages/core/src/types/animated.ts

@@ -53,11 +53,22 @@ export interface AnimationConfig {
    */
   tension: number
   /**
-   * The frequency response.
+   * The natural frequency (in seconds), which dictates the number of bounces
+   * per second when no damping exists.
    *
-   * An alternative to `tension` that describes the speed of an undamped spring.
+   * When defined, `tension` is derived from this, and `friction` is derived
+   * from `tension` and `damping`.
    */
-  speed?: number
+  frequency?: number
+  /**
+   * The damping ratio, which dictates how the spring slows down.
+   *
+   * Set to `0` to never slow down. Set to `1` to slow down without bouncing.
+   * Between `0` and `1` is for you to explore.
+   *
+   * Defaults to `1` when `frequency` is defined.
+   */
+  damping?: number
   /**
    * The damping ratio coefficient, or just the damping ratio when `speed` is defined.
    *