Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
19.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file spring.ts
 * @input Spring parameters in any of the four vocabularies Apple uses
 * @output Exports the `Spring` model, conversions between SwiftUI
 *   (duration, bounce), SwiftUI/WWDC (response, damping ratio),
 *   CASpringAnimation (mass, stiffness, damping) and UIKit's legacy
 *   `usingSpringWithDamping:initialSpringVelocity:` parameters, the closed-form
 *   solution of the spring (`solveSpring`) and of a spring chasing a target
 *   that moves at a constant speed (`solveSpringTowardRamp`), and
 *   `settlingDuration`
 * @position Pure math under the motion animator; no DOM, no React
 *
 * One model, the damped harmonic oscillator m·x″ + c·x′ + k·x = 0, solved in
 * closed form for its three regimes (under-, critically and over-damped). It
 * is the model behind SwiftUI's `Spring`, `CASpringAnimation` and UIKit's
 * spring timing parameters, so a curve computed here is the curve UIKit
 * computes for the same parameters.
 *
 * Units: time in seconds, velocity in units per second (the units of the
 * animated value: px for a translation, 1 for a scale or an opacity), the
 * same units SwiftUI and Core Animation use.
 *
 * Conversions, with their sources:
 * - (duration, bounce) → (mass, stiffness, damping): the three equations of
 *   WWDC23 "Animate with springs" (session 10158):
 *     mass = 1, stiffness = (2π ÷ duration)²,
 *     damping = (1 − bounce) × 4π ÷ duration          for bounce ≥ 0,
 *     damping = 4π ÷ (duration × (1 + bounce))        for bounce < 0.
 * - (response, dampingRatio) → physics: WWDC18 "Designing Fluid Interfaces"
 *   (session 803) defines the response as the period of the undamped spring,
 *   so ω₀ = 2π ÷ response; damping ratio ζ = c ÷ (2·√(k·m)) as stated in
 *   https://developer.apple.com/documentation/uikit/uispringtimingparameters/init(mass:stiffness:damping:initialvelocity:)
 * - UIKit's relative initial velocity: "A value of 1 corresponds to the total
 *   animation distance traversed in one second"
 *   (https://developer.apple.com/documentation/uikit/uiview/animate(withduration:delay:usingspringwithdamping:initialspringvelocity:options:animations:completion:)).
 *
 * Settling duration follows UIKit's own duration solver: the time after which
 * the displacement from the target, for a unit move, stays below ε = 0.001
 * (the epsilon SwiftUI documents for `Spring.settlingDuration`). Underdamped,
 * it is the closed-form time at which the decaying envelope |A| + |B| of
 * A·cos + B·sin falls to ε; critically damped and overdamped, the root of the
 * envelope found numerically. Read from UIKit on the iOS 26.2 simulator, the
 * underdamped values match to the last digit (`CASpringAnimation`
 * `settlingDuration` for every stiffness/damping/velocity in the grid, and the
 * duration UIKit gives `UIView.animate(springDuration:bounce:)`); critically
 * damped ones land within 0.02 % of the duration UIKit picks (it stops 0.0016
 * later in ω₀·t). Core Animation's `settlingDuration` PROPERTY additionally
 * rounds critically damped and overdamped springs up to the next 0.1 s; that
 * rounding is not modeled. Nor is Core Animation's overdamped rendering: with
 * `allowsOverdamping` on (only `UIView.animate(springDuration:bounce:)` with a
 * negative bounce turns it on) Core Animation swaps the two exponentials'
 * coefficients and flips the initial velocity's sign, so its "overdamped"
 * curve overshoots (stiffness 100, damping 40: 104.5 % at 200 ms); every other
 * UIKit spring has it off and is clamped to critical, as `springFromPhysics`
 * does. The bound also reproduces Apple's
 * CASpringAnimation documentation example (stiffness 100, damping 5 →
 * "approximately 2.85 seconds"; damping 15 → "just over 1 second") and
 * WebKit's iOS switch durations, the settling durations of its UIKit-matched
 * springs (0.4880138408543766 s and 0.5073965509413827 s in
 * Source/WebCore/rendering/ios/RenderThemeIOS.h). See spring.test.ts.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/motion/spring.test.ts
 * - /packages/core/src/motion/README.md
 */

const TAU = 2 * Math.PI;

/**
 * A spring, in Core Animation's physical vocabulary. Every other way of
 * describing a spring converts to this one.
 */
export interface Spring {
  /** Mass m of the attached object (`CASpringAnimation.mass`). */
  readonly mass: number;
  /** Stiffness k (`CASpringAnimation.stiffness`). */
  readonly stiffness: number;
  /** Viscous damping coefficient c (`CASpringAnimation.damping`). */
  readonly damping: number;
}

/** SwiftUI's two-parameter description: `Spring(duration:bounce:)`. */
export interface DurationBounce {
  /**
   * Perceptual duration in seconds: the period of the undamped spring, "the
   * pace of the spring".
   */
  readonly duration: number;
  /**
   * 0 is critically damped (no overshoot), up to 1 (undamped oscillation);
   * negative values, down to −1, are overdamped ("flattened") springs.
   */
  readonly bounce: number;
}

/** WWDC18's design-friendly description: response and damping ratio. */
export interface ResponseDamping {
  /** Period of the undamped spring in seconds. */
  readonly response: number;
  /**
   * Damping as a fraction of critical damping (SwiftUI's `dampingFraction`):
   * 1 settles without overshoot, values toward 0 oscillate longer.
   */
  readonly dampingRatio: number;
}

function assertPositiveFinite(name: string, value: number): void {
  if (!(Number.isFinite(value) && value > 0)) {
    throw new RangeError(
      `spring: ${name} must be a positive number, got ${value}`,
    );
  }
}

/**
 * SwiftUI's `Spring(duration:bounce:)` and UIKit's
 * `UIView.animate(springDuration:bounce:…)`: the WWDC23 equations. Bounce is
 * clamped to SwiftUI's documented range (−1, 1].
 *
 * @example
 * ```
 * springFromDurationBounce({duration: 0.5, bounce: 0}); // SwiftUI .smooth
 * ```
 */
export function springFromDurationBounce({
  duration,
  bounce,
}: DurationBounce): Spring {
  assertPositiveFinite('duration', duration);
  if (!Number.isFinite(bounce)) {
    throw new RangeError(`spring: bounce must be finite, got ${bounce}`);
  }
  // −1 itself would be infinite damping.
  const b = Math.min(1, Math.max(-0.999999, bounce));
  const stiffness = (TAU / duration) ** 2;
  const damping =
    b >= 0 ? ((1 - b) * 2 * TAU) / duration : (2 * TAU) / (duration * (1 + b));
  return {mass: 1, stiffness, damping};
}

/**
 * SwiftUI's `Spring(response:dampingRatio:)` and
 * `Animation.spring(response:dampingFraction:)`. Overdamping (ratio > 1) is
 * kept, as SwiftUI keeps it for this initializer.
 */
export function springFromResponse({
  response,
  dampingRatio,
}: ResponseDamping): Spring {
  assertPositiveFinite('response', response);
  if (!(Number.isFinite(dampingRatio) && dampingRatio >= 0)) {
    throw new RangeError(
      `spring: dampingRatio must be ≥ 0, got ${dampingRatio}`,
    );
  }
  const omega = TAU / response;
  return {mass: 1, stiffness: omega * omega, damping: 2 * dampingRatio * omega};
}

/**
 * `CASpringAnimation` / `UISpringTimingParameters(mass:stiffness:damping:)`
 * / SwiftUI `Spring(mass:stiffness:damping:allowOverDamping:)`. Like SwiftUI,
 * an overdamped spring is treated as critically damped unless
 * `allowOverdamping` is set: "a value of false specifies that such cases
 * should instead be treated as critically damped".
 */
export function springFromPhysics({
  mass = 1,
  stiffness,
  damping,
  allowOverdamping = false,
}: {
  mass?: number;
  stiffness: number;
  damping: number;
  allowOverdamping?: boolean;
}): Spring {
  assertPositiveFinite('mass', mass);
  assertPositiveFinite('stiffness', stiffness);
  if (!(Number.isFinite(damping) && damping >= 0)) {
    throw new RangeError(`spring: damping must be ≥ 0, got ${damping}`);
  }
  const critical = 2 * Math.sqrt(stiffness * mass);
  return {
    mass,
    stiffness,
    damping: allowOverdamping ? damping : Math.min(damping, critical),
  };
}

/** Undamped angular frequency ω₀ = √(k/m), rad/s. */
export function naturalFrequency(spring: Spring): number {
  return Math.sqrt(spring.stiffness / spring.mass);
}

/** Damping ratio ζ = c / (2·√(k·m)). */
export function dampingRatioOf(spring: Spring): number {
  return spring.damping / (2 * Math.sqrt(spring.stiffness * spring.mass));
}

/** Response (period of the undamped spring), seconds. */
export function responseOf(spring: Spring): number {
  return TAU / naturalFrequency(spring);
}

/** The spring as SwiftUI's (duration, bounce), inverting the WWDC23 equations. */
export function durationBounceOf(spring: Spring): DurationBounce {
  const zeta = dampingRatioOf(spring);
  return {
    duration: responseOf(spring),
    bounce: zeta <= 1 ? 1 - zeta : 1 / zeta - 1,
  };
}

/** The spring as (response, dampingRatio). */
export function responseDampingOf(spring: Spring): ResponseDamping {
  return {response: responseOf(spring), dampingRatio: dampingRatioOf(spring)};
}

/**
 * A spring in any of the vocabularies the constants table uses: physical
 * (mass, stiffness, damping), SwiftUI (duration, bounce) or WWDC18
 * (response, dampingRatio). Tables keep the vocabulary of their source so a
 * value reads exactly as it was published.
 */
export type SpringDescription =
  | {
      readonly mass?: number;
      readonly stiffness: number;
      readonly damping: number;
    }
  | DurationBounce
  | ResponseDamping;

/**
 * Normalizes a description to the physical `Spring`. A physical description
 * gets `springFromPhysics`' treatment: overdamping is clamped to critical, as
 * SwiftUI and Core Animation do by default.
 */
export function toSpring(description: SpringDescription): Spring {
  if ('stiffness' in description) {
    return springFromPhysics(description);
  }
  if ('bounce' in description) {
    return springFromDurationBounce(description);
  }
  return springFromResponse(description);
}

/**
 * UIKit's relative initial spring velocity for a move from `from` to `to`
 * at `velocity` units/s: 1 means the whole distance in one second. Undefined
 * (±Infinity) when `from === to`; animate in absolute units instead
 * (`solveSpring` takes an absolute velocity).
 */
export function relativeVelocity(
  velocity: number,
  from: number,
  to: number,
): number {
  return velocity / (to - from);
}

/** Inverse of `relativeVelocity`: absolute units/s. */
export function absoluteVelocity(
  relative: number,
  from: number,
  to: number,
): number {
  return relative * (to - from);
}

/** A spring released from a value with a velocity, heading for a target. */
export interface SpringCurve {
  readonly spring: Spring;
  readonly from: number;
  readonly to: number;
  /** Initial velocity, units/s. */
  readonly initialVelocity: number;
  /** Value at `t` seconds after release. */
  value(t: number): number;
  /** Velocity at `t` seconds after release, units/s. */
  velocity(t: number): number;
  /**
   * The time after which |value(t) − to| stays below `threshold` (in the
   * value's own units) for good: the envelope bound used by
   * `settlingDuration`, applied in absolute units. 0 when already within.
   * Infinity for an undamped spring that is displaced or moving.
   */
  settleTime(threshold: number): number;
}

// |ζ − 1| below this is solved as critically damped: the under/overdamped
// forms lose precision as ωd or the root gap goes to zero, and the critical
// form differs from them by O(|ζ − 1|) there.
const CRITICAL_TOLERANCE = 1e-6;

/**
 * Closed-form solution of the spring released at `from` with
 * `initialVelocity` (units/s), heading for `to`.
 *
 * @example
 * ```
 * const curve = solveSpring(springFromDurationBounce({duration: 0.5, bounce: 0}), {from: 0, to: 300});
 * curve.value(0.1); // px after 100 ms
 * ```
 */
export function solveSpring(
  spring: Spring,
  {
    from,
    to,
    velocity: initialVelocity = 0,
  }: {from: number; to: number; velocity?: number},
): SpringCurve {
  const omega0 = naturalFrequency(spring);
  const zeta = dampingRatioOf(spring);
  // Displacement from the target; the ODE is solved for x(t) = value − to.
  const x0 = from - to;
  const v0 = initialVelocity;
  let displacement: (t: number) => number;
  let speed: (t: number) => number;
  let envelope: (t: number) => number;
  // Where the envelope peaks (critically damped only; elsewhere 0).
  let envelopePeak = 0;

  if (zeta < 1 - CRITICAL_TOLERANCE) {
    const decay = zeta * omega0;
    const omegaD = omega0 * Math.sqrt(1 - zeta * zeta);
    const a = x0;
    const b = (v0 + decay * x0) / omegaD;
    const bv = (decay * v0 + omega0 * omega0 * x0) / omegaD;
    displacement = t =>
      Math.exp(-decay * t) *
      (a * Math.cos(omegaD * t) + b * Math.sin(omegaD * t));
    speed = t =>
      Math.exp(-decay * t) *
      (v0 * Math.cos(omegaD * t) - bv * Math.sin(omegaD * t));
    const amplitude = Math.abs(a) + Math.abs(b);
    envelope = t => amplitude * Math.exp(-decay * t);
  } else if (zeta <= 1 + CRITICAL_TOLERANCE) {
    const b = v0 + omega0 * x0;
    displacement = t => (x0 + b * t) * Math.exp(-omega0 * t);
    speed = t => (v0 - omega0 * b * t) * Math.exp(-omega0 * t);
    const absA = Math.abs(x0);
    const absB = Math.abs(b);
    envelope = t => (absA + absB * t) * Math.exp(-omega0 * t);
    // (|A| + |B|·t)·e^(−ω₀t) rises until t = 1/ω₀ − |A|/|B|, then decays.
    envelopePeak = absB > 0 ? Math.max(0, 1 / omega0 - absA / absB) : 0;
  } else {
    const root = omega0 * Math.sqrt(zeta * zeta - 1);
    const r1 = -zeta * omega0 + root; // slow root
    const r2 = -zeta * omega0 - root; // fast root
    const c1 = (v0 - r2 * x0) / (r1 - r2);
    const c2 = x0 - c1;
    displacement = t => c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);
    speed = t => r1 * c1 * Math.exp(r1 * t) + r2 * c2 * Math.exp(r2 * t);
    const absC1 = Math.abs(c1);
    const absC2 = Math.abs(c2);
    envelope = t => absC1 * Math.exp(r1 * t) + absC2 * Math.exp(r2 * t);
  }

  const settleTime = (threshold: number): number => {
    if (!(threshold > 0)) {
      return Infinity;
    }
    if (zeta === 0) {
      return x0 === 0 && v0 === 0 ? 0 : Infinity;
    }
    const start = envelopePeak;
    if (envelope(start) <= threshold) {
      // `start` is where the bound peaks (0 when it only decays), so the
      // bound is within the threshold everywhere.
      return 0;
    }
    if (zeta < 1 - CRITICAL_TOLERANCE) {
      // Closed form: amplitude · e^(−ζω₀t) = threshold.
      const amplitude = envelope(0);
      return Math.log(amplitude / threshold) / (zeta * omega0);
    }
    // Monotone decreasing after `start`: bracket, then bisect.
    let lo = start;
    let hi = Math.max(start, 1 / omega0);
    while (envelope(hi) > threshold) {
      lo = hi;
      hi *= 2;
      if (hi > 1e6) {
        return Infinity;
      }
    }
    for (let i = 0; i < 100 && hi - lo > 1e-12; i++) {
      const mid = (lo + hi) / 2;
      if (envelope(mid) > threshold) {
        lo = mid;
      } else {
        hi = mid;
      }
    }
    return hi;
  };

  return {
    spring,
    from,
    to,
    initialVelocity,
    value: t => to + displacement(t),
    velocity: t => speed(t),
    settleTime,
  };
}

/** A spring chasing a target that moves at a constant speed. */
export interface SpringRampCurve {
  readonly spring: Spring;
  /** Value at `t` seconds after the start. */
  value(t: number): number;
  /** Velocity at `t` seconds after the start, units/s. */
  velocity(t: number): number;
  /**
   * How far behind the moving target the spring settles: c·slope ÷ k
   * (it then moves at the target's speed).
   */
  readonly lag: number;
}

/**
 * A spring whose target moves at a constant speed, `target + slope · t`: the
 * "tracking" springs UIKit drives per frame (a press that keeps deepening, a
 * lift that follows the finger). Closed form: the spring settles `lag` behind
 * the moving target, and what is left is a free spring around that point,
 * solved by `solveSpring`. Chain pieces (a new slope, a fixed target) by
 * starting each from the previous piece's value and velocity.
 */
export function solveSpringTowardRamp(
  spring: Spring,
  {
    from,
    velocity: initialVelocity = 0,
    target,
    slope,
  }: {from: number; velocity?: number; target: number; slope: number},
): SpringRampCurve {
  const lag = (spring.damping * slope) / spring.stiffness;
  // x(t) = target + slope·t − lag + h(t), with h a free spring around 0.
  const free = solveSpring(spring, {
    from: from - target + lag,
    to: 0,
    velocity: initialVelocity - slope,
  });
  return {
    spring,
    lag,
    value: t => target + slope * t - lag + free.value(t),
    velocity: t => slope + free.velocity(t),
  };
}

/** Core Animation's settling epsilon (documented for SwiftUI's Spring). */
export const SETTLING_EPSILON = 0.001;

/**
 * `CASpringAnimation.settlingDuration` / SwiftUI `Spring.settlingDuration`:
 * seconds until a unit move (target 1) stays within `epsilon` of its target.
 * `initialVelocity` is UIKit's relative velocity (distance fractions per
 * second, positive toward the target), 0 by default as in SwiftUI.
 */
export function settlingDuration(
  spring: Spring,
  {
    initialVelocity = 0,
    epsilon = SETTLING_EPSILON,
  }: {initialVelocity?: number; epsilon?: number} = {},
): number {
  return solveSpring(spring, {
    from: 0,
    to: 1,
    velocity: initialVelocity,
  }).settleTime(epsilon);
}

/**
 * ω₀ · duration that UIKit's legacy spring derivation lands on, by damping
 * ratio, for a release at rest. Read from UIKit
 * (`UIView.animate(withDuration: 1, usingSpringWithDamping: ζ,
 * initialSpringVelocity: 0)`; `UIViewPropertyAnimator(duration:dampingRatio:)`
 * gives identical springs, and ω₀ scales as 1 ÷ duration): measured: UIKit
 * lab (injected host app), iOS 26.2 sim iPhone 17 Pro, CAAnimation read,
 * Oct 23 2026.
 */
const UIKIT_LEGACY_OMEGA_DURATION: ReadonlyArray<readonly [number, number]> = [
  [0.1, 46.102],
  [0.15, 33.4801],
  [0.2, 26.5936],
  [0.25, 22.2149],
  [0.3, 19.1698],
  [0.35, 16.9236],
  [0.4, 15.1966],
  [0.45, 13.8275],
  [0.5, 12.7169],
  [0.55, 11.8001],
  [0.6, 11.0335],
  [0.65, 10.3869],
  [0.7, 9.8396],
  [0.75, 9.3779],
  [0.8, 8.9943],
  [0.85, 8.6897],
  [0.9, 8.4808],
  [0.95, 8.4425],
  [1, 9.2334],
];

/**
 * UIKit's legacy `animate(withDuration:delay:usingSpringWithDamping:
 * initialSpringVelocity:…)`: the caller fixes the total duration and the
 * damping ratio, and UIKit derives the spring: mass 1, the given damping
 * ratio, and ω₀ = c(ζ) ÷ duration with c read from UIKit every 0.05 of ζ from
 * 0.1 to 1 (at ζ 1 the spring settles exactly at the duration). The animation
 * is cut at the duration.
 *
 * GUESS between the measured ratios (linear interpolation, within 0.05 of a
 * read) and below 0.1 (extrapolated as c ∝ 1 ÷ ζ). A non-zero initial
 * velocity shifts UIKit's root slightly, and at low ratios makes its solver
 * jump to a far smaller one (ζ 0.1, velocity 1 → ω₀·D 9.74); neither is
 * modeled. Measurement task M-K1.
 */
export function springFromUIKitDampingDuration({
  duration,
  dampingRatio,
}: {
  duration: number;
  dampingRatio: number;
}): Spring {
  assertPositiveFinite('duration', duration);
  // UIKit's ratio is clamped to (0, 1]: it has no overdamped springs.
  const zeta = Math.min(1, Math.max(1e-3, dampingRatio));
  const table = UIKIT_LEGACY_OMEGA_DURATION;
  let c = (table[0][1] * table[0][0]) / zeta;
  for (let i = 0; i + 1 < table.length; i++) {
    const [z0, c0] = table[i];
    const [z1, c1] = table[i + 1];
    if (zeta >= z0 && zeta <= z1) {
      c = c0 + ((c1 - c0) * (zeta - z0)) / (z1 - z0);
      break;
    }
  }
  const omega0 = c / duration;
  return {mass: 1, stiffness: omega0 * omega0, damping: 2 * zeta * omega0};
}