@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/motion/spring.ts

@@ -0,0 +1,551 @@
+// 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};
+}