Make animation and router support simulation, and use Spring for Cupertino (#155575)

This PR makes `TransitionRoute` support driving the animation with
`Simulation`. This is needed for Cupertino widgets, since iOS use
"spring simulations" for a majority of their animations.

This PR also applies the standard spring animation to
`CupertinoDialogRoute` (alert dialogs) and `CupertinoModalPopupRoute`
(action sheets). (This PR does not yet support customizing the spring
parameters or conveniently using the springs for custom routes, which
are left for future PRs.)

### Comparison

I tried to create a comparison video for action sheets, however the
difference is far less noticeable than I expected. (All clips are
precisely aligned at the moment the pointer is lifted.) I guess the
original curve _is_ good enough. Nevertheless, the spring simulation is
the correct one and we should support it.

Edit: [The
comment](flutter/flutter#155575 (comment))
below also mentioned that supporting spring animation will improve the
fidelity when the animation is caused by a user gesture. I assume this
requires initial speed, which is not supported by this PR but we can add
it in the future.


https://github.com/user-attachments/assets/06d2f684-ad1c-4a4d-8663-a561895f45e9

Also, Flutter's response seems to be always a moment slower than
SwiftUI, possibly because Flutter requiring two frames to start the
animation (one frame to add the transition widget, one frame for the
animation to actually progress.) We probably want to solve it in the
future.

## Pre-launch Checklist

- [ ] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [ ] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [ ] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [ ] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [ ] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [ ] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: dkwingsmt

packages/flutter/lib/src/animation/animation_controller.dart

@@ -383,8 +383,8 @@ class AnimationController extends Animation<double>
   ///  * [stop], which aborts the animation without changing its value or status
   ///    and without dispatching any notifications other than completing or
   ///    canceling the [TickerFuture].
-  ///  * [forward], [reverse], [animateTo], [animateWith], [fling], and [repeat],
-  ///    which start the animation controller.
+  ///  * [forward], [reverse], [animateTo], [animateWith], [animateBackWith],
+  ///    [fling], and [repeat], which start the animation controller.
   set value(double newValue) {
     stop();
     _internalSetValue(newValue);
@@ -802,6 +802,7 @@ class AnimationController extends Animation<double>
 
   /// Drives the animation according to the given simulation.
   ///
+  /// {@template flutter.animation.AnimationController.animateWith}
   /// The values from the simulation are clamped to the [lowerBound] and
   /// [upperBound]. To avoid this, consider creating the [AnimationController]
   /// using the [AnimationController.unbounded] constructor.
@@ -811,9 +812,15 @@ class AnimationController extends Animation<double>
   /// The most recently returned [TickerFuture], if any, is marked as having been
   /// canceled, meaning the future never completes and its [TickerFuture.orCancel]
   /// derivative future completes with a [TickerCanceled] error.
+  /// {@endtemplate}
   ///
   /// The [status] is always [AnimationStatus.forward] for the entire duration
   /// of the simulation.
+  ///
+  /// See also:
+  ///
+  ///  * [animateBackWith], which is like this method but the status is always
+  ///    [AnimationStatus.reverse].
   TickerFuture animateWith(Simulation simulation) {
     assert(
       _ticker != null,
@@ -825,6 +832,29 @@ class AnimationController extends Animation<double>
     return _startSimulation(simulation);
   }
 
+  /// Drives the animation according to the given simulation with a [status] of
+  /// [AnimationStatus.reverse].
+  ///
+  /// {@macro flutter.animation.AnimationController.animateWith}
+  ///
+  /// The [status] is always [AnimationStatus.reverse] for the entire duration
+  /// of the simulation.
+  ///
+  /// See also:
+  ///
+  ///  * [animateWith], which is like this method but the status is always
+  ///    [AnimationStatus.forward].
+  TickerFuture animateBackWith(Simulation simulation) {
+    assert(
+      _ticker != null,
+      'AnimationController.animateWith() called after AnimationController.dispose()\n'
+      'AnimationController methods should not be used after calling dispose.',
+    );
+    stop();
+    _direction = _AnimationDirection.reverse;
+    return _startSimulation(simulation);
+  }
+
   TickerFuture _startSimulation(Simulation simulation) {
     assert(!isAnimating);
     _simulation = simulation;

packages/flutter/lib/src/cupertino/route.dart

@@ -20,6 +20,7 @@ import 'dart:ui' show ImageFilter;
 
 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
+import 'package:flutter/physics.dart';
 import 'package:flutter/rendering.dart';
 import 'package:flutter/widgets.dart';
 
@@ -1065,6 +1066,30 @@ class _CupertinoEdgeShadowPainter extends BoxPainter {
   }
 }
 
+// The stiffness used by dialogs and action sheets.
+//
+// The stiffness value is obtained by examining the properties of
+// `CASpringAnimation` in Xcode. The damping value is derived similarly, with
+// additional precision calculated based on `_kStandardStiffness` to ensure a
+// damping ratio of 1 (critically damped): damping = 2 * sqrt(stiffness)
+const double _kStandardStiffness = 522.35;
+const double _kStandardDamping = 45.7099552;
+const SpringDescription _kStandardSpring = SpringDescription(
+  mass: 1,
+  stiffness: _kStandardStiffness,
+  damping: _kStandardDamping,
+);
+// The iOS spring animation duration is 0.404 seconds, based on the properties
+// of `CASpringAnimation` in Xcode. At this point, the spring's position
+// `x(0.404)` is approximately 0.9990000, suggesting that iOS uses a position
+// tolerance of 1e-3 (matching the default `_epsilonDefault` value).
+//
+// However, the spring's velocity `dx(0.404)` is about 0.02, indicating that iOS
+// may not consider velocity when determining the animation's end condition. To
+// account for this, a larger velocity tolerance is applied here for added
+// safety.
+const Tolerance _kStandardTolerance = Tolerance(velocity: 0.03);
+
 /// A route that shows a modal iOS-style popup that slides up from the
 /// bottom of the screen.
 ///
@@ -1144,29 +1169,21 @@ class CupertinoModalPopupRoute<T> extends PopupRoute<T> {
   @override
   Duration get transitionDuration => _kModalPopupTransitionDuration;
 
-  CurvedAnimation? _animation;
-
-  late Tween<Offset> _offsetTween;
-
   /// {@macro flutter.widgets.DisplayFeatureSubScreen.anchorPoint}
   final Offset? anchorPoint;
 
   @override
-  Animation<double> createAnimation() {
-    assert(_animation == null);
-    _animation = CurvedAnimation(
-      parent: super.createAnimation(),
-
-      // These curves were initially measured from native iOS horizontal page
-      // route animations and seemed to be a good match here as well.
-      curve: Curves.linearToEaseOut,
-      reverseCurve: Curves.linearToEaseOut.flipped,
-    );
-    _offsetTween = Tween<Offset>(
-      begin: const Offset(0.0, 1.0),
-      end: Offset.zero,
+  Simulation createSimulation({ required bool forward }) {
+    assert(!debugTransitionCompleted(), 'Cannot reuse a $runtimeType after disposing it.');
+    final double end = forward ? 1.0 : 0.0;
+    return SpringSimulation(
+      _kStandardSpring,
+      controller!.value,
+      end,
+      0,
+      tolerance: _kStandardTolerance,
+      snapToEnd: true,
     );
-    return _animation!;
   }
 
   @override
@@ -1185,17 +1202,16 @@ class CupertinoModalPopupRoute<T> extends PopupRoute<T> {
     return Align(
       alignment: Alignment.bottomCenter,
       child: FractionalTranslation(
-        translation: _offsetTween.evaluate(_animation!),
+        translation: _offsetTween.evaluate(animation),
         child: child,
       ),
     );
   }
 
-  @override
-  void dispose() {
-    _animation?.dispose();
-    super.dispose();
-  }
+  static final Tween<Offset> _offsetTween = Tween<Offset>(
+    begin: const Offset(0.0, 1.0),
+    end: Offset.zero,
+  );
 }
 
 /// Shows a modal iOS-style popup that slides up from the bottom of the screen.
@@ -1286,12 +1302,6 @@ Future<T?> showCupertinoModalPopup<T>({
   );
 }
 
-// The curve and initial scale values were mostly eyeballed from iOS, however
-// they reuse the same animation curve that was modeled after native page
-// transitions.
-final Animatable<double> _dialogScaleTween = Tween<double>(begin: 1.3, end: 1.0)
-  .chain(CurveTween(curve: Curves.linearToEaseOut));
-
 Widget _buildCupertinoDialogTransitions(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation, Widget child) {
   return child;
 }
@@ -1439,33 +1449,36 @@ class CupertinoDialogRoute<T> extends RawDialogRoute<T> {
   CurvedAnimation? _fadeAnimation;
 
   @override
-  Widget buildTransitions(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation, Widget child) {
+  Simulation createSimulation({ required bool forward }) {
+    assert(!debugTransitionCompleted(), 'Cannot reuse a $runtimeType after disposing it.');
+    final double end = forward ? 1.0 : 0.0;
+    return SpringSimulation(
+      _kStandardSpring,
+      controller!.value,
+      end,
+      0,
+      tolerance: _kStandardTolerance,
+      snapToEnd: true,
+    );
+  }
 
+  @override
+  Widget buildTransitions(BuildContext context, Animation<double> animation, Animation<double> secondaryAnimation, Widget child) {
     if (transitionBuilder != null) {
       return super.buildTransitions(context, animation, secondaryAnimation, child);
     }
 
-    if (_fadeAnimation?.parent != animation) {
-      _fadeAnimation?.dispose();
-      _fadeAnimation = CurvedAnimation(
-        parent: animation,
-        curve: Curves.easeInOut,
-      );
-    }
-
-    final CurvedAnimation fadeAnimation = _fadeAnimation!;
-
     if (animation.status == AnimationStatus.reverse) {
       return FadeTransition(
-        opacity: fadeAnimation,
-        child: super.buildTransitions(context, animation, secondaryAnimation, child),
+        opacity: animation,
+        child: child,
       );
     }
     return FadeTransition(
-      opacity: fadeAnimation,
+      opacity: animation,
       child: ScaleTransition(
         scale: animation.drive(_dialogScaleTween),
-        child: super.buildTransitions(context, animation, secondaryAnimation, child),
+        child: child,
       ),
     );
   }
@@ -1475,4 +1488,9 @@ class CupertinoDialogRoute<T> extends RawDialogRoute<T> {
     _fadeAnimation?.dispose();
     super.dispose();
   }
+
+  // The curve and initial scale values were mostly eyeballed from iOS, however
+  // they reuse the same animation curve that was modeled after native page
+  // transitions.
+  static final Tween<double> _dialogScaleTween = Tween<double>(begin: 1.3, end: 1.0);
 }

packages/flutter/lib/src/physics/spring_simulation.dart

@@ -139,17 +139,25 @@ class SpringSimulation extends Simulation {
   /// The units for the velocity are L/T, where L is the aforementioned
   /// arbitrary unit of length, and T is the time unit used for driving the
   /// [SpringSimulation].
+  ///
+  /// If `snapToEnd` is true, [x] will be set to `end` and [dx] to 0 when
+  /// [isDone] returns true. This is useful for transitions that require the
+  /// simulation to stop exactly at the end value, since the spring may not
+  /// naturally reach the target precisely. Defaults to false.
   SpringSimulation(
     SpringDescription spring,
     double start,
     double end,
     double velocity, {
+    bool snapToEnd = false,
     super.tolerance,
   }) : _endPosition = end,
-       _solution = _SpringSolution(spring, start - end, velocity);
+       _solution = _SpringSolution(spring, start - end, velocity),
+       _snapToEnd = snapToEnd;
 
   final double _endPosition;
   final _SpringSolution _solution;
+  final bool _snapToEnd;
 
   /// The kind of spring being simulated, for debugging purposes.
   ///
@@ -158,10 +166,22 @@ class SpringSimulation extends Simulation {
   SpringType get type => _solution.type;
 
   @override
-  double x(double time) => _endPosition + _solution.x(time);
+  double x(double time) {
+    if (_snapToEnd && isDone(time)) {
+      return _endPosition;
+    } else {
+      return _endPosition + _solution.x(time);
+    }
+  }
 
   @override
-  double dx(double time) => _solution.dx(time);
+  double dx(double time) {
+    if (_snapToEnd && isDone(time)) {
+      return 0;
+    } else {
+      return _solution.dx(time);
+    }
+  }
 
   @override
   bool isDone(double time) {