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>
b35c6be8c9