feat: Introduce ClampingWithOverscrollPhysics scroll physics

gonuit · gonuit · commit c350e5c0b3c6 · 2024-01-05T01:01:46.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 3.1.0-dev.1
+- Experimental: 
+  - Added `ClampingWithOverscrollPhysics` scroll physics, that together with indicator controller allows handling overscroll correctly.
+- The indicator's cancel duration is now based on the dragging progress.
+- Updated the the dart sdk constraints to `>=2.17.0 <4.0.0`
 ## 3.0.0
 - **CustomRefreshIndicator**:
   - Deprecated *indicatorFinalizeDuration*, *indicatorSettleDuration*, *indicatorCancelDuration* and *completeStateDuration* parameters in favor of *durations*.
diff --git a/example/lib/main.dart b/example/lib/main.dart
@@ -5,7 +5,7 @@ import 'package:example/screens/programmatically_controlled_indicator_screen.dar
 import 'package:example/widgets/web_frame.dart';
 import 'package:flutter/material.dart';
 
-import 'screens/opacity_indicator_screen.dart';
+import 'screens/custom_material_indicator_screen.dart';
 import 'screens/fetch_more_screen.dart';
 import 'screens/ice_cream_indicator_screen.dart';
 import 'screens/plane_indicator_screen.dart';
@@ -29,7 +29,7 @@ class MyApp extends StatelessWidget {
       home: const MainScreen(),
       builder: (context, child) => WebFrame(child: child),
       routes: {
-        '/example': (context) => const OpacityIndicatorScreen(),
+        '/example': (context) => const CustomMaterialIndicatorScreen(),
         '/plane': (context) => const PlaneIndicatorScreen(),
         '/ice-cream': (context) => const IceCreamIndicatorScreen(),
         '/presentation': (context) => const PresentationScreen(),
@@ -74,7 +74,7 @@ class MainScreen extends StatelessWidget {
               child: Container(
                 height: 50,
                 alignment: Alignment.center,
-                child: const Text("Multidirectional indicator"),
+                child: const Text("Multidirectional Indicator"),
               ),
               onPressed: () => Navigator.pushNamed(
                 context,
@@ -87,7 +87,7 @@ class MainScreen extends StatelessWidget {
                 height: 50,
                 alignment: Alignment.center,
                 child:
-                    const Text("Custom material indicator with list opacity"),
+                    const Text("Custom Material Indicator"),
               ),
               onPressed: () => Navigator.pushNamed(
                 context,
diff --git a/example/lib/screens/custom_material_indicator_screen.dart b/example/lib/screens/custom_material_indicator_screen.dart
@@ -0,0 +1,64 @@
+import 'package:custom_refresh_indicator/custom_refresh_indicator.dart';
+import 'package:example/widgets/example_app_bar.dart';
+import 'package:example/widgets/example_list.dart';
+import 'package:flutter/material.dart';
+
+class CustomMaterialIndicatorScreen extends StatefulWidget {
+  const CustomMaterialIndicatorScreen({super.key});
+
+  @override
+  State<CustomMaterialIndicatorScreen> createState() => _CustomMaterialIndicatorScreenState();
+}
+
+class _CustomMaterialIndicatorScreenState extends State<CustomMaterialIndicatorScreen> {
+  final _controller = IndicatorController();
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: appBackgroundColor,
+      appBar: const ExampleAppBar(
+        elevation: 0,
+      ),
+      body: SafeArea(
+        child: Container(
+          clipBehavior: Clip.hardEdge,
+          decoration: BoxDecoration(
+            border: Border.all(
+              color: const Color(0xFFE2D8D7),
+            ),
+          ),
+          child: CustomMaterialIndicator(
+            controller: _controller,
+            clipBehavior: Clip.antiAlias,
+            trigger: IndicatorTrigger.bothEdges,
+            triggerMode: IndicatorTriggerMode.anywhere,
+            onRefresh: () => Future.delayed(const Duration(seconds: 2)),
+            indicatorBuilder: (context, controller) {
+              return const Icon(
+                Icons.ac_unit,
+                color: appContentColor,
+                size: 30,
+              );
+            },
+            scrollableBuilder: (context, child, controller) {
+              return child;
+            },
+            child: ExampleList(
+              itemCount: 12,
+              physics: AlwaysScrollableScrollPhysics(
+                parent: ClampingWithOverscrollPhysics(state: _controller),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+
+  @override
+  void dispose() {
+    _controller.dispose();
+    super.dispose();
+  }
+}
diff --git a/example/lib/screens/opacity_indicator_screen.dart b/example/lib/screens/opacity_indicator_screen.dart
diff --git a/example/lib/widgets/example_app_bar.dart b/example/lib/widgets/example_app_bar.dart
@@ -6,11 +6,13 @@ const appContentColor = Color(0xff877162);
 class ExampleAppBar extends StatelessWidget implements PreferredSizeWidget {
   final String? title;
   final List<Widget>? actions;
+  final double elevation;
 
   const ExampleAppBar({
     super.key,
     this.title,
     this.actions,
+    this.elevation = 1.0,
   });
 
   @override
@@ -27,7 +29,7 @@ class ExampleAppBar extends StatelessWidget implements PreferredSizeWidget {
         ),
       ),
       actions: actions,
-      elevation: 3,
+      elevation: elevation,
     );
   }
 
diff --git a/example/lib/widgets/example_list.dart b/example/lib/widgets/example_list.dart
@@ -7,13 +7,17 @@ class ExampleList extends StatelessWidget {
   final bool countElements;
   final bool reverse;
   final Color backgroundColor;
+  final ScrollPhysics physics;
 
   const ExampleList({
     super.key,
     this.reverse = false,
     this.countElements = false,
     this.backgroundColor = appBackgroundColor,
     this.itemCount = 4,
+    this.physics = const AlwaysScrollableScrollPhysics(
+      parent: ClampingScrollPhysics(),
+    ),
   });
 
   @override
@@ -31,10 +35,8 @@ class ExampleList extends StatelessWidget {
         ],
       ),
       child: ListView.separated(
+        physics: physics,
         reverse: reverse,
-        physics: const AlwaysScrollableScrollPhysics(
-          parent: ClampingScrollPhysics(),
-        ),
         itemBuilder: (BuildContext context, int index) => countElements
             ? Element(
                 child: Center(
diff --git a/example/pubspec.lock b/example/pubspec.lock
@@ -47,7 +47,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "3.0.0"
+    version: "3.1.0-dev.1"
   fake_async:
     dependency: transitive
     description:
diff --git a/lib/custom_refresh_indicator.dart b/lib/custom_refresh_indicator.dart
@@ -2,4 +2,5 @@ export 'src/data/data.dart';
 export 'src/custom_refresh_indicator.dart';
 export 'src/delegates/delegates.dart';
 export 'src/widgets/widgets.dart';
+export 'src/physics/physics.dart';
 export 'src/utils/utils.dart';
diff --git a/lib/src/controller.dart b/lib/src/controller.dart
@@ -1,7 +1,11 @@
 part of 'custom_refresh_indicator.dart';
 
 class IndicatorController extends Animation<double>
-    with AnimationEagerListenerMixin, AnimationLocalListenersMixin, AnimationLocalStatusListenersMixin {
+    with
+        AnimationEagerListenerMixin,
+        AnimationLocalListenersMixin,
+        AnimationLocalStatusListenersMixin,
+        ClampingWithOverscrollPhysicsState {
   double _value;
 
   /// Current indicator value / progress
@@ -121,7 +125,7 @@ class IndicatorController extends Animation<double>
   /// will have the direction of `AxisDirection.left`
   AxisDirection get direction => _direction;
 
-  /// Whether list scrolls horrizontally
+  /// Whether list scrolls horizontally
   ///
   /// (direction equals `AxisDirection.left` or `AxisDirection.right`)
   bool get isHorizontalDirection => direction == AxisDirection.left || direction == AxisDirection.right;
diff --git a/lib/src/custom_refresh_indicator.dart b/lib/src/custom_refresh_indicator.dart
@@ -155,7 +155,7 @@ class CustomRefreshIndicator extends StatefulWidget {
   }
 
   CustomRefreshIndicator({
-    Key? key,
+    super.key,
     required this.child,
     required this.onRefresh,
     required this.builder,
@@ -189,8 +189,7 @@ class CustomRefreshIndicator extends StatefulWidget {
           settleDuration: indicatorSettleDuration ?? durations.settleDuration,
         ),
         // set the default extent percentage value if not provided
-        containerExtentPercentageToArmed = containerExtentPercentageToArmed ?? defaultContainerExtentPercentageToArmed,
-        super(key: key);
+        containerExtentPercentageToArmed = containerExtentPercentageToArmed ?? defaultContainerExtentPercentageToArmed;
 
   @override
   CustomRefreshIndicatorState createState() => CustomRefreshIndicatorState();
@@ -388,6 +387,8 @@ class CustomRefreshIndicatorState extends State<CustomRefreshIndicator> with Tic
   }
 
   bool _handleScrollEndNotification(ScrollEndNotification notification) {
+    controller.clearPhysicsState();
+
     if (controller.state.isArmed) {
       _start();
     } else {
@@ -578,9 +579,10 @@ class CustomRefreshIndicatorState extends State<CustomRefreshIndicator> with Tic
   Future<void> _hide() async {
     setIndicatorState(IndicatorState.canceling);
     _dragOffset = 0;
+    final progress = _animationController.value;
     await _animationController.animateTo(
       0.0,
-      duration: widget.durations.cancelDuration,
+      duration: widget.durations.cancelDuration * progress,
       curve: Curves.ease,
     );
 
@@ -600,7 +602,6 @@ class CustomRefreshIndicatorState extends State<CustomRefreshIndicator> with Tic
     );
 
     final builder = widget.builder;
-
     if (widget.autoRebuild ||
         // ignore: deprecated_member_use_from_same_package
         (builder is IndicatorBuilderDelegate && (builder as IndicatorBuilderDelegate).autoRebuild)) {
diff --git a/lib/src/physics/clamping_with_overscroll_physics.dart b/lib/src/physics/clamping_with_overscroll_physics.dart
@@ -0,0 +1,110 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/widgets.dart';
+import 'package:meta/meta.dart';
+
+/// Keeps overscroll data for the [ClampingWithOverscrollPhysics] scroll
+/// physics.
+///
+/// Implemented by the [IndicatorController] class.
+mixin ClampingWithOverscrollPhysicsState {
+  double _overscroll = 0;
+
+  /// Returns true when overscroll is available.
+  bool get _hasOverscroll => _overscroll > 0;
+
+  void _addOverscroll(double delta) {
+    _overscroll += delta;
+    if (_overscroll < 0) {
+      _overscroll = 0;
+    }
+  }
+
+  void _removeOverscroll(double delta) {
+    _overscroll -= delta;
+    if (_overscroll < 0) {
+      _overscroll = 0;
+    }
+  }
+
+  @internal
+  void clearPhysicsState() {
+    _overscroll = 0;
+  }
+}
+
+/// Creates scroll physics that prevent the scroll offset from exceeding the
+/// bounds of the content while handling the overscroll.
+class ClampingWithOverscrollPhysics extends ClampingScrollPhysics {
+  final ClampingWithOverscrollPhysicsState _state;
+
+  /// Creates scroll physics that prevent the scroll offset from exceeding the
+  /// bounds of the content while handling the overscroll.
+  const ClampingWithOverscrollPhysics({
+    super.parent,
+    required ClampingWithOverscrollPhysicsState state,
+  }) : _state = state;
+
+  @override
+  ClampingWithOverscrollPhysics applyTo(ScrollPhysics? ancestor) {
+    return ClampingWithOverscrollPhysics(
+      parent: buildParent(ancestor),
+      state: _state,
+    );
+  }
+
+  @override
+  double applyBoundaryConditions(ScrollMetrics position, double value) {
+    assert(() {
+      if (value == position.pixels) {
+        throw FlutterError.fromParts(<DiagnosticsNode>[
+          ErrorSummary('$runtimeType.applyBoundaryConditions() was called redundantly.'),
+          ErrorDescription(
+            'The proposed new position, $value, is exactly equal to the current position of the '
+            'given ${position.runtimeType}, ${position.pixels}.\n'
+            'The applyBoundaryConditions method should only be called when the value is '
+            'going to actually change the pixels, otherwise it is redundant.',
+          ),
+          DiagnosticsProperty<ScrollPhysics>('The physics object in question was', this,
+              style: DiagnosticsTreeStyle.errorProperty),
+          DiagnosticsProperty<ScrollMetrics>('The position object in question was', position,
+              style: DiagnosticsTreeStyle.errorProperty),
+        ]);
+      }
+      return true;
+    }());
+
+    if (value < position.pixels && position.pixels <= position.minScrollExtent) {
+      // Underscroll.
+
+      final delta = value - position.pixels;
+      _state._addOverscroll(delta.abs());
+      return delta;
+    }
+    if (position.maxScrollExtent <= position.pixels && position.pixels < value) {
+      // Overscroll.
+      final delta = value - position.pixels;
+      _state._addOverscroll(delta);
+      return delta;
+    }
+    if (value < position.minScrollExtent && position.minScrollExtent < position.pixels) {
+      // Hit top edge.
+      final delta = value - position.minScrollExtent;
+      _state._addOverscroll(delta);
+      return delta;
+    }
+    if (position.pixels < position.maxScrollExtent && position.maxScrollExtent < value) {
+      // Hit bottom edge.
+      final delta = value - position.maxScrollExtent;
+      _state._addOverscroll(delta);
+      return delta;
+    }
+    if (_state._hasOverscroll) {
+      final delta = value - position.pixels;
+      _state._removeOverscroll(delta.abs());
+
+      return delta;
+    } else {
+      return 0;
+    }
+  }
+}
diff --git a/lib/src/physics/physics.dart b/lib/src/physics/physics.dart
@@ -0,0 +1 @@
+export 'clamping_with_overscroll_physics.dart';
diff --git a/lib/src/widgets/custom_material_indicator.dart b/lib/src/widgets/custom_material_indicator.dart
diff --git a/pubspec.yaml b/pubspec.yaml
