Module spring

Expand description

Damped harmonic oscillator (spring) animation.

Provides physically-based motion for smooth, natural UI transitions. Based on the classical damped spring equation:

F = -stiffness × (position - target) - damping × velocity

§Parameters

stiffness (k): Restoring force strength. Higher = faster response. Typical range: 100–400 for UI motion.
damping (c): Velocity drag. Higher = less oscillation.
- Underdamped (c < 2√k): oscillates past target before settling
- Critically damped (c ≈ 2√k): fastest convergence without overshoot
- Overdamped (c > 2√k): slow convergence, no overshoot
rest_threshold: Position delta below which the spring is considered at rest. Default: 0.001.

Uses semi-implicit Euler integration for stability. The tick() method accepts a Duration and internally converts to seconds for the physics step.

value() returns a normalized position in [0.0, 1.0] (clamped).
position() returns the raw (unclamped) position for full-range use.
A spring at rest (is_complete() == true) will not resume unless set_target() or reset() is called.
reset() returns position to the initial value and zeroes velocity.
Stiffness and damping are always positive (clamped on construction).

Very large dt: Integration may overshoot badly. Callers should cap dt to a reasonable frame budget (e.g., 33ms). For dt > 100ms, the spring subdivides into smaller steps for stability.
Zero stiffness: Spring will never converge; clamped to minimum 0.1.
Zero damping: Spring oscillates forever; not a failure mode, but is_complete() may never return true.