Add macOS-specific scroll physics (#108298)

Author: moffatman

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

@@ -480,6 +480,9 @@ class CupertinoScrollBehavior extends ScrollBehavior {
 
   @override
   ScrollPhysics getScrollPhysics(BuildContext context) {
+    if (getPlatform(context) == TargetPlatform.macOS) {
+      return const BouncingScrollPhysics(decelerationRate: ScrollDecelerationRate.fast);
+    }
     return const BouncingScrollPhysics();
   }
 }

packages/flutter/lib/src/gestures/velocity_tracker.dart

@@ -373,3 +373,61 @@ class IOSScrollViewFlingVelocityTracker extends VelocityTracker {
     }
   }
 }
+
+/// A [VelocityTracker] subclass that provides a close approximation of macOS
+/// scroll view's velocity estimation strategy.
+///
+/// The estimated velocity reported by this class is a close approximation of
+/// the velocity a macOS scroll view would report with the same
+/// [PointerMoveEvent]s, when the touch that initiates a fling is released.
+///
+/// This class differs from the [VelocityTracker] class in that it uses weighted
+/// average of the latest few velocity samples of the tracked pointer, instead
+/// of doing a linear regression on a relatively large amount of data points, to
+/// estimate the velocity of the tracked pointer. Adding data points and
+/// estimating the velocity are both cheap.
+///
+/// To obtain a velocity, call [getVelocity] or [getVelocityEstimate]. The
+/// estimated velocity is typically used as the initial flinging velocity of a
+/// `Scrollable`, when its drag gesture ends.
+class MacOSScrollViewFlingVelocityTracker extends IOSScrollViewFlingVelocityTracker {
+  /// Create a new MacOSScrollViewFlingVelocityTracker.
+  MacOSScrollViewFlingVelocityTracker(super.kind);
+
+  @override
+  VelocityEstimate getVelocityEstimate() {
+    // The velocity estimated using this expression is an approximation of the
+    // scroll velocity of a macOS scroll view at the moment the user touch was
+    // released.
+    final Offset estimatedVelocity = _previousVelocityAt(-2) * 0.15
+                                   + _previousVelocityAt(-1) * 0.65
+                                   + _previousVelocityAt(0) * 0.2;
+
+    final _PointAtTime? newestSample = _touchSamples[_index];
+    _PointAtTime? oldestNonNullSample;
+
+    for (int i = 1; i <= IOSScrollViewFlingVelocityTracker._sampleSize; i += 1) {
+      oldestNonNullSample = _touchSamples[(_index + i) % IOSScrollViewFlingVelocityTracker._sampleSize];
+      if (oldestNonNullSample != null) {
+        break;
+      }
+    }
+
+    if (oldestNonNullSample == null || newestSample == null) {
+      assert(false, 'There must be at least 1 point in _touchSamples: $_touchSamples');
+      return const VelocityEstimate(
+        pixelsPerSecond: Offset.zero,
+        confidence: 0.0,
+        duration: Duration.zero,
+        offset: Offset.zero,
+      );
+    } else {
+      return VelocityEstimate(
+        pixelsPerSecond: estimatedVelocity,
+        confidence: 1.0,
+        duration: newestSample.time - oldestNonNullSample.time,
+        offset: newestSample.point - oldestNonNullSample.point,
+      );
+    }
+  }
+}

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

@@ -10,6 +10,22 @@ import 'simulation.dart';
 
 export 'tolerance.dart' show Tolerance;
 
+/// Numerically determine the input value which produces output value [target]
+/// for a function [f], given its first-derivative [df].
+double _newtonsMethod({
+  required double initialGuess,
+  required double target,
+  required double Function(double) f,
+  required double Function(double) df,
+  required int iterations
+}) {
+  double guess = initialGuess;
+  for (int i = 0; i < iterations; i++) {
+    guess = guess - (f(guess) - target) / df(guess);
+  }
+  return guess;
+}
+
 /// A simulation that applies a drag to slow a particle down.
 ///
 /// Models a particle affected by fluid drag, e.g. air resistance.
@@ -26,10 +42,20 @@ class FrictionSimulation extends Simulation {
     double position,
     double velocity, {
     super.tolerance,
+    double constantDeceleration = 0
   }) : _drag = drag,
        _dragLog = math.log(drag),
        _x = position,
-       _v = velocity;
+       _v = velocity,
+       _constantDeceleration = constantDeceleration * velocity.sign {
+      _finalTime = _newtonsMethod(
+        initialGuess: 0,
+        target: 0,
+        f: dx,
+        df: (double time) => (_v * math.pow(_drag, time) * _dragLog) - _constantDeceleration,
+        iterations: 10
+      );
+    }
 
   /// Creates a new friction simulation with its fluid drag coefficient (_cₓ_) set so
   /// as to ensure that the simulation starts and ends at the specified
@@ -58,6 +84,12 @@ class FrictionSimulation extends Simulation {
   final double _dragLog;
   final double _x;
   final double _v;
+  final double _constantDeceleration;
+  // The time at which the simulation should be stopped.
+  // This is needed when constantDeceleration is not zero (on Desktop), when
+  // using the pure friction simulation, acceleration naturally reduces to zero
+  // and creates a stopping point.
+  double _finalTime = double.infinity; // needs to be infinity for newtonsMethod call in constructor.
 
   // Return the drag value for a FrictionSimulation whose x() and dx() values pass
   // through the specified start and end position/velocity values.
@@ -71,13 +103,28 @@ class FrictionSimulation extends Simulation {
   }
 
   @override
-  double x(double time) => _x + _v * math.pow(_drag, time) / _dragLog - _v / _dragLog;
+  double x(double time) {
+    if (time > _finalTime) {
+      return finalX;
+    }
+    return _x + _v * math.pow(_drag, time) / _dragLog - _v / _dragLog - ((_constantDeceleration / 2) * time * time);
+  }
 
   @override
-  double dx(double time) => _v * math.pow(_drag, time);
+  double dx(double time) {
+    if (time > _finalTime) {
+      return 0;
+    }
+    return _v * math.pow(_drag, time) - _constantDeceleration * time;
+  }
 
   /// The value of [x] at `double.infinity`.
-  double get finalX => _x - _v / _dragLog;
+  double get finalX {
+    if (_constantDeceleration == 0) {
+      return _x - _v / _dragLog;
+    }
+    return x(_finalTime);
+  }
 
   /// The time at which the value of `x(time)` will equal [x].
   ///
@@ -89,11 +136,19 @@ class FrictionSimulation extends Simulation {
     if (_v == 0.0 || (_v > 0 ? (x < _x || x > finalX) : (x > _x || x < finalX))) {
       return double.infinity;
     }
-    return math.log(_dragLog * (x - _x) / _v + 1.0) / _dragLog;
+    return _newtonsMethod(
+      target: x,
+      initialGuess: 0,
+      f: this.x,
+      df: dx,
+      iterations: 10
+    );
   }
 
   @override
-  bool isDone(double time) => dx(time).abs() < tolerance.velocity;
+  bool isDone(double time) {
+    return dx(time).abs() < tolerance.velocity;
+  }
 
   @override
   String toString() => '${objectRuntimeType(this, 'FrictionSimulation')}(cₓ: ${_drag.toStringAsFixed(1)}, x₀: ${_x.toStringAsFixed(1)}, dx₀: ${_v.toStringAsFixed(1)})';

packages/flutter/lib/src/widgets/scroll_configuration.dart

@@ -219,8 +219,9 @@ class ScrollBehavior {
   GestureVelocityTrackerBuilder velocityTrackerBuilder(BuildContext context) {
     switch (getPlatform(context)) {
       case TargetPlatform.iOS:
-      case TargetPlatform.macOS:
         return (PointerEvent event) => IOSScrollViewFlingVelocityTracker(event.kind);
+      case TargetPlatform.macOS:
+        return (PointerEvent event) => MacOSScrollViewFlingVelocityTracker(event.kind);
       case TargetPlatform.android:
       case TargetPlatform.fuchsia:
       case TargetPlatform.linux:
@@ -230,6 +231,10 @@ class ScrollBehavior {
   }
 
   static const ScrollPhysics _bouncingPhysics = BouncingScrollPhysics(parent: RangeMaintainingScrollPhysics());
+  static const ScrollPhysics _bouncingDesktopPhysics = BouncingScrollPhysics(
+    decelerationRate: ScrollDecelerationRate.fast,
+    parent: RangeMaintainingScrollPhysics()
+  );
   static const ScrollPhysics _clampingPhysics = ClampingScrollPhysics(parent: RangeMaintainingScrollPhysics());
 
   /// The scroll physics to use for the platform given by [getPlatform].
@@ -240,8 +245,9 @@ class ScrollBehavior {
   ScrollPhysics getScrollPhysics(BuildContext context) {
     switch (getPlatform(context)) {
       case TargetPlatform.iOS:
-      case TargetPlatform.macOS:
         return _bouncingPhysics;
+      case TargetPlatform.macOS:
+        return _bouncingDesktopPhysics;
       case TargetPlatform.android:
       case TargetPlatform.fuchsia:
       case TargetPlatform.linux:

packages/flutter/lib/src/widgets/scroll_physics.dart

@@ -16,6 +16,17 @@ import 'scroll_simulation.dart';
 
 export 'package:flutter/physics.dart' show ScrollSpringSimulation, Simulation, Tolerance;
 
+/// The rate at which scroll momentum will be decelerated.
+enum ScrollDecelerationRate {
+  /// Standard deceleration, aligned with mobile software expectations.
+  normal,
+  /// Increased deceleration, aligned with desktop software expectations.
+  ///
+  /// Appropriate for use with input devices more precise than touch screens,
+  /// such as trackpads or mouse wheels.
+  fast
+}
+
 // Examples can assume:
 // class FooScrollPhysics extends ScrollPhysics {
 //   const FooScrollPhysics({ super.parent });
@@ -608,7 +619,13 @@ class RangeMaintainingScrollPhysics extends ScrollPhysics {
 ///    of different types to get the desired scroll physics.
 class BouncingScrollPhysics extends ScrollPhysics {
   /// Creates scroll physics that bounce back from the edge.
-  const BouncingScrollPhysics({ super.parent });
+  const BouncingScrollPhysics({
+    this.decelerationRate = ScrollDecelerationRate.normal,
+    super.parent,
+  });
+
+  /// Used to determine parameters for friction simulations.
+  final ScrollDecelerationRate decelerationRate;
 
   @override
   BouncingScrollPhysics applyTo(ScrollPhysics? ancestor) {
@@ -623,7 +640,14 @@ class BouncingScrollPhysics extends ScrollPhysics {
   /// This factor starts at 0.52 and progressively becomes harder to overscroll
   /// as more of the area past the edge is dragged in (represented by an increasing
   /// `overscrollFraction` which starts at 0 when there is no overscroll).
-  double frictionFactor(double overscrollFraction) => 0.52 * math.pow(1 - overscrollFraction, 2);
+  double frictionFactor(double overscrollFraction) {
+    switch (decelerationRate) {
+      case ScrollDecelerationRate.fast:
+        return 0.07 * math.pow(1 - overscrollFraction, 2);
+      case ScrollDecelerationRate.normal:
+        return 0.52 * math.pow(1 - overscrollFraction, 2);
+    }
+  }
 
   @override
   double applyPhysicsToUserOffset(ScrollMetrics position, double offset) {
@@ -670,13 +694,23 @@ class BouncingScrollPhysics extends ScrollPhysics {
   Simulation? createBallisticSimulation(ScrollMetrics position, double velocity) {
     final Tolerance tolerance = this.tolerance;
     if (velocity.abs() >= tolerance.velocity || position.outOfRange) {
+      double constantDeceleration;
+      switch (decelerationRate) {
+        case ScrollDecelerationRate.fast:
+          constantDeceleration = 1400;
+          break;
+        case ScrollDecelerationRate.normal:
+          constantDeceleration = 0;
+          break;
+      }
       return BouncingScrollSimulation(
         spring: spring,
         position: position.pixels,
         velocity: velocity,
         leadingExtent: position.minScrollExtent,
         trailingExtent: position.maxScrollExtent,
         tolerance: tolerance,
+        constantDeceleration: constantDeceleration
       );
     }
     return null;
@@ -711,6 +745,30 @@ class BouncingScrollPhysics extends ScrollPhysics {
   // from the natural motion of lifting the finger after a scroll.
   @override
   double get dragStartDistanceMotionThreshold => 3.5;
+
+  @override
+  double get maxFlingVelocity {
+    switch (decelerationRate) {
+      case ScrollDecelerationRate.fast:
+        return kMaxFlingVelocity * 8.0;
+      case ScrollDecelerationRate.normal:
+        return super.maxFlingVelocity;
+    }
+  }
+
+  @override
+  SpringDescription get spring {
+    switch (decelerationRate) {
+      case ScrollDecelerationRate.fast:
+        return SpringDescription.withDampingRatio(
+          mass: 0.3,
+          stiffness: 75.0,
+          ratio: 1.3,
+        );
+      case ScrollDecelerationRate.normal:
+        return super.spring;
+    }
+  }
 }
 
 /// Scroll physics for environments that prevent the scroll offset from reaching

packages/flutter/lib/src/widgets/scroll_simulation.dart

@@ -34,6 +34,7 @@ class BouncingScrollSimulation extends Simulation {
     required this.leadingExtent,
     required this.trailingExtent,
     required this.spring,
+    double constantDeceleration = 0,
     super.tolerance,
   }) : assert(position != null),
        assert(velocity != null),
@@ -50,7 +51,7 @@ class BouncingScrollSimulation extends Simulation {
     } else {
       // Taken from UIScrollView.decelerationRate (.normal = 0.998)
       // 0.998^1000 = ~0.135
-      _frictionSimulation = FrictionSimulation(0.135, position, velocity);
+      _frictionSimulation = FrictionSimulation(0.135, position, velocity, constantDeceleration: constantDeceleration);
       final double finalX = _frictionSimulation.finalX;
       if (velocity > 0.0 && finalX > trailingExtent) {
         _springTime = _frictionSimulation.timeAtX(trailingExtent);

packages/flutter/test/cupertino/picker_test.dart

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import 'package:flutter/cupertino.dart';
+import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/rendering.dart';
 import 'package:flutter/services.dart';
@@ -397,9 +398,11 @@ void main() {
         warnIfMissed: false, // has an IgnorePointer
       );
 
-      // Should have been flung far enough that even the first item goes off
-      // screen and gets removed.
-      expect(find.widgetWithText(SizedBox, '0').evaluate().isEmpty, true);
+      if (debugDefaultTargetPlatformOverride == TargetPlatform.iOS) {
+        // Should have been flung far enough that even the first item goes off
+        // screen and gets removed.
+        expect(find.widgetWithText(SizedBox, '0').evaluate().isEmpty, true);
+      }
 
       expect(
         selectedItems,
@@ -421,7 +424,7 @@ void main() {
         // Falling back to 0 shouldn't produce more callbacks.
         <int>[8, 6, 4, 2, 0],
       );
-    }, variant: const TargetPlatformVariant(<TargetPlatform>{ TargetPlatform.iOS,  TargetPlatform.macOS }));
+    }, variant: const TargetPlatformVariant(<TargetPlatform>{ TargetPlatform.iOS, TargetPlatform.macOS }));
   });
 
   testWidgets('Picker adapts to MaterialApp dark mode', (WidgetTester tester) async {