Add withDurationAndBounce to SpringDescription (#164411)

Part of https://github.com/flutter/flutter/issues/152587 ### Description: With `withDurationAndBounce` (we could also rename to `withDuration`), the user only has to worry about a single attribute: the bounce (and duration, but they would have to worry with duration anyway. If they don't, there is a default value already). The standard `SpringDescription` has 3 values, so it is way more abstract. This should help a lot people to make beautiful spring animations using Flutter. <img width="838" alt="image" src="https://github.com/user-attachments/assets/4d0dccc7-0f97-4a13-99a4-268228b87f08" /> ### Negative bounce: I didn't enable bounce to be negative because the behavior is super tricky. I don't know what formula Apple is using, but seems like it is not public. There are many different formulas we can use, including the one provided on the original issue, but then there is the risk of people complaining it works differently than SwiftUI. I need to check if other projects (react-spring, framer motion) support negative bounce, but feels like this is something 99.9999% of people wouldn't expect or use, so I think we are safe. I couldn't find a single usage of negative bounce on Swift in all GitHub (without a duration, using code-search, vs 5k cases with positive values). Not even sure the todo is needed, but won't hurt. ### Comparison <details> <summary>Dart vs Swift testing results</summary> ```dart testWidgets('Spring Simulation Tests - Matching SwiftUI', (WidgetTester tester) async { // Test cases matching the Swift code's ranges List<({Duration duration, double bounce})> testCases = [ (duration: const Duration(milliseconds: 100), bounce: 0.0), (duration: const Duration(milliseconds: 100), bounce: 0.3), (duration: const Duration(milliseconds: 100), bounce: 0.8), (duration: const Duration(milliseconds: 100), bounce: 1.0), (duration: const Duration(milliseconds: 500), bounce: 0.0), (duration: const Duration(milliseconds: 500), bounce: 0.3), (duration: const Duration(milliseconds: 500), bounce: 0.8), (duration: const Duration(milliseconds: 500), bounce: 1.0), (duration: const Duration(milliseconds: 1000), bounce: 0.0), (duration: const Duration(milliseconds: 1000), bounce: 0.3), (duration: const Duration(milliseconds: 1000), bounce: 0.8), (duration: const Duration(milliseconds: 1000), bounce: 1.0), (duration: const Duration(milliseconds: 2000), bounce: 0.0), (duration: const Duration(milliseconds: 2000), bounce: 0.3), (duration: const Duration(milliseconds: 2000), bounce: 0.8), (duration: const Duration(milliseconds: 2000), bounce: 1.0), ]; for (final testCase in testCases) { SpringDescription springDesc = SpringDescription.withDurationAndBounce( duration: testCase.duration, bounce: testCase.bounce, ); print( 'Duration: ${testCase.duration.inMilliseconds / 1000}, Bounce: ${testCase.bounce}, Mass: ${springDesc.mass}, Stiffness: ${springDesc.stiffness}, Damping: ${springDesc.damping}', ); } }); ``` Output: ``` Duration: 0.1, Bounce: 0.0, Mass: 1.0, Stiffness: 3947.8417604357423, Damping: 125.66370614359171 Duration: 0.1, Bounce: 0.3, Mass: 1.0, Stiffness: 3947.8417604357423, Damping: 87.9645943005142 Duration: 0.1, Bounce: 0.8, Mass: 1.0, Stiffness: 3947.8417604357423, Damping: 25.132741228718338 Duration: 0.1, Bounce: 1.0, Mass: 1.0, Stiffness: 3947.8417604357423, Damping: 0.0 Duration: 0.5, Bounce: 0.0, Mass: 1.0, Stiffness: 157.91367041742973, Damping: 25.132741228718345 Duration: 0.5, Bounce: 0.3, Mass: 1.0, Stiffness: 157.91367041742973, Damping: 17.59291886010284 Duration: 0.5, Bounce: 0.8, Mass: 1.0, Stiffness: 157.91367041742973, Damping: 5.026548245743668 Duration: 0.5, Bounce: 1.0, Mass: 1.0, Stiffness: 157.91367041742973, Damping: 0.0 Duration: 1.0, Bounce: 0.0, Mass: 1.0, Stiffness: 39.47841760435743, Damping: 12.566370614359172 Duration: 1.0, Bounce: 0.3, Mass: 1.0, Stiffness: 39.47841760435743, Damping: 8.79645943005142 Duration: 1.0, Bounce: 0.8, Mass: 1.0, Stiffness: 39.47841760435743, Damping: 2.513274122871834 Duration: 1.0, Bounce: 1.0, Mass: 1.0, Stiffness: 39.47841760435743, Damping: 0.0 Duration: 2.0, Bounce: 0.0, Mass: 1.0, Stiffness: 9.869604401089358, Damping: 6.283185307179586 Duration: 2.0, Bounce: 0.3, Mass: 1.0, Stiffness: 9.869604401089358, Damping: 4.39822971502571 Duration: 2.0, Bounce: 0.8, Mass: 1.0, Stiffness: 9.869604401089358, Damping: 1.256637061435917 Duration: 2.0, Bounce: 1.0, Mass: 1.0, Stiffness: 9.869604401089358, Damping: 0.0 ``` Swift: ```swift import SwiftUI import XCTest class SpringParameterTests: XCTestCase { func printSpringParameters(duration: Double, bounce: Double) { let spring = Spring(duration: duration, bounce: bounce) // Let SwiftUI do its thing print("Duration: \(duration), Bounce: \(bounce), Mass: \(spring.mass), Stiffness: \(spring.stiffness), Damping: \(spring.damping)") } func testParameterExtraction() { // Test a range of durations and bounces let durations: [Double] = [0.1, 0.5, 1.0, 2.0] let bounces: [Double] = [0.0, 0.3, 0.8, 1.0] for duration in durations { for bounce in bounces { printSpringParameters(duration: duration, bounce: bounce) } } } } ``` Output: ``` Duration: 0.1, Bounce: 0.0, Mass: 1.0, Stiffness: 3947.8417604357433, Damping: 125.66370614359172 Duration: 0.1, Bounce: 0.3, Mass: 1.0, Stiffness: 3947.841760435743, Damping: 87.96459430051421 Duration: 0.1, Bounce: 0.8, Mass: 1.0, Stiffness: 3947.8417604357423, Damping: 25.132741228718338 Duration: 0.1, Bounce: 1.0, Mass: 1.0, Stiffness: 3947.8417604357433, Damping: 0.0 Duration: 0.5, Bounce: 0.0, Mass: 1.0, Stiffness: 157.91367041742973, Damping: 25.132741228718345 Duration: 0.5, Bounce: 0.3, Mass: 1.0, Stiffness: 157.9136704174297, Damping: 17.59291886010284 Duration: 0.5, Bounce: 0.8, Mass: 1.0, Stiffness: 157.9136704174297, Damping: 5.026548245743668 Duration: 0.5, Bounce: 1.0, Mass: 1.0, Stiffness: 157.91367041742973, Damping: 0.0 Duration: 1.0, Bounce: 0.0, Mass: 1.0, Stiffness: 39.47841760435743, Damping: 12.566370614359172 Duration: 1.0, Bounce: 0.3, Mass: 1.0, Stiffness: 39.478417604357425, Damping: 8.79645943005142 Duration: 1.0, Bounce: 0.8, Mass: 1.0, Stiffness: 39.478417604357425, Damping: 2.513274122871834 Duration: 1.0, Bounce: 1.0, Mass: 1.0, Stiffness: 39.47841760435743, Damping: 0.0 Duration: 2.0, Bounce: 0.0, Mass: 1.0, Stiffness: 9.869604401089358, Damping: 6.283185307179586 Duration: 2.0, Bounce: 0.3, Mass: 1.0, Stiffness: 9.869604401089356, Damping: 4.39822971502571 Duration: 2.0, Bounce: 0.8, Mass: 1.0, Stiffness: 9.869604401089356, Damping: 1.256637061435917 Duration: 2.0, Bounce: 1.0, Mass: 1.0, Stiffness: 9.869604401089358, Damping: 0.0 ``` There are minor differences which should be rounding errors. </details>
2025-03-11 04:44:29 -03:00 · 2025-03-11 04:44:29 -03:00 · b35c6be8c9
commit b35c6be8c9
parent d452d04a07
2 changed files with 140 additions and 0 deletions
--- a/packages/flutter/lib/src/physics/spring_simulation.dart
+++ b/packages/flutter/lib/src/physics/spring_simulation.dart
@ -43,6 +43,44 @@ class SpringDescription {
    double ratio = 1.0,
  }) : damping = ratio * 2.0 * math.sqrt(mass * stiffness);

+  /// Creates a [SpringDescription] based on a desired animation duration and
+  /// bounce.
+  ///
+  /// This provides an intuitive way to define a spring based on its visual
+  /// properties, [duration] and [bounce]. Check the properties' documentation
+  /// for their definition.
+  ///
+  /// This constructor produces the same result as SwiftUI's
+  /// `spring(duration:bounce:blendDuration:)` animation.
+  ///
+  /// {@tool snippet}
+  /// ```dart
+  /// final SpringDescription spring = SpringDescription.withDurationAndBounce(
+  ///   duration: const Duration(milliseconds: 300),
+  ///   bounce: 0.3,
+  /// );
+  /// ```
+  /// {@end-tool}
+  ///
+  /// See also:
+  /// * [SpringDescription], which creates a spring by explicitly providing
+  /// physical parameters.
+  /// * [SpringDescription.withDampingRatio], which creates a spring with a
+  ///   damping ratio and other physical parameters.
+  factory SpringDescription.withDurationAndBounce({
+    Duration duration = const Duration(milliseconds: 500),
+    double bounce = 0.0,
+  }) {
+    assert(duration.inMilliseconds > 0, 'Duration must be positive');
+    final double durationInSeconds = duration.inMilliseconds / Duration.millisecondsPerSecond;
+    const double mass = 1.0;
+    final double stiffness = (4 * math.pi * math.pi * mass) / math.pow(durationInSeconds, 2);
+    final double dampingRatio = bounce > 0 ? (1.0 - bounce) : (1 / (bounce + 1));
+    final double damping = dampingRatio * 2.0 * math.sqrt(mass * stiffness);
+
+    return SpringDescription(mass: mass, stiffness: stiffness, damping: damping);
+  }
+
  /// The mass of the spring (m).
  ///
  /// The units are arbitrary, but all springs within a system should use
@ -78,6 +116,43 @@ class SpringDescription {
  /// driving the [SpringSimulation].
  final double damping;

+  /// The duration parameter used in [SpringDescription.withDurationAndBounce].
+  ///
+  /// This value defines the perceptual duration of the spring, controlling
+  /// its overall pace. It is approximately equal to the time it takes for
+  /// the spring to settle, but for highly bouncy springs, it instead
+  /// corresponds to the oscillation period.
+  ///
+  /// This duration does not represent the exact time for the spring to stop
+  /// moving. For example, when [bounce] is 1, the spring oscillates
+  /// indefinitely, even though [duration] has a finite value. To determine
+  /// when the motion has effectively stopped within a certain tolerance,
+  /// use [SpringSimulation.isDone].
+  ///
+  /// Defaults to 0.5 seconds.
+  Duration get duration {
+    final double durationInSeconds = math.sqrt((4 * math.pi * math.pi * mass) / stiffness);
+    final int milliseconds = (durationInSeconds * Duration.millisecondsPerSecond).round();
+    return Duration(milliseconds: milliseconds);
+  }
+
+  /// The bounce parameter used in [SpringDescription.withDurationAndBounce].
+  ///
+  /// This value controls how bouncy the spring is:
+  ///
+  ///  * A value of 0 results in a critically damped spring with no oscillation.
+  ///  * Values between 0 and 1 produce underdamping, where the spring oscillates a few times
+  ///    before settling. A value of 1 represents an undamped spring that
+  ///    oscillates indefinitely.
+  ///  * Negative values indicate overdamping, where the motion is slow and
+  ///    resistive, like moving through a thick fluid.
+  ///
+  /// Defaults to 0.
+  double get bounce {
+    final double dampingRatio = damping / (2.0 * math.sqrt(mass * stiffness));
+    return dampingRatio < 1.0 ? (1.0 - dampingRatio) : ((1 / dampingRatio) - 1);
+  }
+
  @override
  String toString() =>
      '${objectRuntimeType(this, 'SpringDescription')}(mass: ${mass.toStringAsFixed(1)}, stiffness: ${stiffness.toStringAsFixed(1)}, damping: ${damping.toStringAsFixed(1)})';
--- a/packages/flutter/test/physics/spring_simulation_test.dart
+++ b/packages/flutter/test/physics/spring_simulation_test.dart
@ -35,4 +35,69 @@ void main() {
    expect(snappingSimulation.x(time), 1);
    expect(snappingSimulation.dx(time), 0);
  });
+
+  group('SpringDescription.withDurationAndBounce', () {
+    test('creates spring with expected results', () {
+      final SpringDescription spring = SpringDescription.withDurationAndBounce(bounce: 0.3);
+
+      expect(spring.mass, equals(1.0));
+      expect(spring.stiffness, moreOrLessEquals(157.91, epsilon: 0.01));
+      expect(spring.damping, moreOrLessEquals(17.59, epsilon: 0.01));
+
+      // Verify that getters recalculate correctly
+      expect(spring.bounce, moreOrLessEquals(0.3, epsilon: 0.0001));
+      expect(spring.duration.inMilliseconds, equals(500));
+    });
+
+    test('creates spring with negative bounce', () {
+      final SpringDescription spring = SpringDescription.withDurationAndBounce(bounce: -0.3);
+
+      expect(spring.mass, equals(1.0));
+      expect(spring.stiffness, moreOrLessEquals(157.91, epsilon: 0.01));
+      expect(spring.damping, moreOrLessEquals(35.90, epsilon: 0.01));
+
+      // Verify that getters recalculate correctly
+      expect(spring.bounce, moreOrLessEquals(-0.3, epsilon: 0.0001));
+      expect(spring.duration.inMilliseconds, equals(500));
+    });
+
+    test('get duration and bounce based on mass and stiffness', () {
+      const SpringDescription spring = SpringDescription(
+        mass: 1.0,
+        stiffness: 157.91,
+        damping: 17.59,
+      );
+
+      expect(spring.bounce, moreOrLessEquals(0.3, epsilon: 0.001));
+      expect(spring.duration.inMilliseconds, equals(500));
+    });
+
+    test('custom duration', () {
+      final SpringDescription spring = SpringDescription.withDurationAndBounce(
+        duration: const Duration(milliseconds: 100),
+      );
+
+      expect(spring.mass, equals(1.0));
+      expect(spring.stiffness, moreOrLessEquals(3947.84, epsilon: 0.01));
+      expect(spring.damping, moreOrLessEquals(125.66, epsilon: 0.01));
+
+      expect(spring.bounce, moreOrLessEquals(0, epsilon: 0.001));
+      expect(spring.duration.inMilliseconds, equals(100));
+    });
+
+    test('duration <= 0 should fail', () {
+      expect(
+        () => SpringDescription.withDurationAndBounce(
+          duration: const Duration(seconds: -1),
+          bounce: 0.3,
+        ),
+        throwsA(isAssertionError),
+      );
+
+      expect(
+        () => SpringDescription.withDurationAndBounce(duration: Duration.zero, bounce: 0.3),
+        throwsA(isAssertionError),
+      );
+    });
+  });
 }