Rename stretching to bouncing

cookbook/lib/showcase/ai_playlist_generator.dart

@@ -106,7 +106,7 @@ final _confirmRoute = GoRoute(
     return const ScrollableNavigationSheetPage(
       initialExtent: Extent.proportional(0.7),
       minExtent: Extent.proportional(0.7),
-      physics: StretchingSheetPhysics(
+      physics: BouncingSheetPhysics(
         parent: SnappingSheetPhysics(),
       ),
       child: _ConfirmPage(),

cookbook/lib/showcase/airbnb_mobile_app.dart

@@ -164,7 +164,7 @@ class _ContentSheet extends StatelessWidget {
           ),
         );
 
-        final sheetPhysics = StretchingSheetPhysics(
+        final sheetPhysics = BouncingSheetPhysics(
           parent: SnappingSheetPhysics(
             snappingBehavior: SnapToNearest(
               snapTo: [

cookbook/lib/showcase/safari/menu.dart

@@ -26,7 +26,7 @@ class MenuSheet extends StatelessWidget {
     return ScrollableSheet(
       initialExtent: halfWayExtent,
       minExtent: halfWayExtent,
-      physics: const StretchingSheetPhysics(
+      physics: const BouncingSheetPhysics(
         parent: SnappingSheetPhysics(),
       ),
       child: ClipRRect(

cookbook/lib/tutorial/bottom_bar_visibility.dart

@@ -137,7 +137,7 @@ class _ExampleSheet extends StatelessWidget {
     const halfSize = Extent.proportional(0.5);
     const fullSize = Extent.proportional(1);
 
-    final multiStopPhysics = StretchingSheetPhysics(
+    final multiStopPhysics = BouncingSheetPhysics(
       parent: SnappingSheetPhysics(
         snappingBehavior: SnapToNearest(
           snapTo: const [minSize, halfSize, fullSize],

cookbook/lib/tutorial/cupertino_modal_sheet.dart

@@ -68,7 +68,7 @@ class _HalfScreenSheet extends StatelessWidget {
     return const DraggableSheet(
       initialExtent: Extent.proportional(0.5),
       minExtent: Extent.proportional(0.5),
-      physics: StretchingSheetPhysics(
+      physics: BouncingSheetPhysics(
         parent: SnappingSheetPhysics(),
       ),
       child: _SheetContent(),

cookbook/lib/tutorial/extent_driven_animation.dart

@@ -50,7 +50,7 @@ class _ExampleSheet extends StatelessWidget {
     final bottomPadding = MediaQuery.of(context).padding.bottom;
     final minExtent = Extent.pixels(56 + bottomPadding);
 
-    final physics = StretchingSheetPhysics(
+    final physics = BouncingSheetPhysics(
       parent: SnappingSheetPhysics(
         snappingBehavior: SnapToNearest(
           snapTo: [minExtent, const Extent.proportional(1)],

cookbook/lib/tutorial/scrollable_sheet.dart

@@ -46,7 +46,7 @@ class _MySheet extends StatelessWidget {
       // Optional: Comment out the following lines to add multiple stop positions.
       //
       // minExtent: const Extent.proportional(0.2),
-      // physics: StretchingSheetPhysics(
+      // physics: BouncingSheetPhysics(
       //   parent: SnappingSheetPhysics(
       //     snappingBehavior: SnapToNearest(
       //       snapTo: [

cookbook/lib/tutorial/sheet_content_scaffold.dart

@@ -50,7 +50,7 @@ class _ExampleSheet extends StatelessWidget {
       ),
     );
 
-    final physics = StretchingSheetPhysics(
+    final physics = BouncingSheetPhysics(
       parent: SnappingSheetPhysics(
         snappingBehavior: SnapToNearest(
           snapTo: [

cookbook/lib/tutorial/sheet_controller.dart

@@ -89,7 +89,7 @@ class _ExampleSheet extends StatelessWidget {
     return DraggableSheet(
       controller: controller,
       minExtent: const Extent.proportional(0.5),
-      physics: const StretchingSheetPhysics(
+      physics: const BouncingSheetPhysics(
         parent: SnappingSheetPhysics(),
       ),
       child: Card(

cookbook/lib/tutorial/sheet_draggable.dart

@@ -66,7 +66,7 @@ class _ExampleSheet extends StatelessWidget {
     );
 
     const minExtent = Extent.proportional(0.5);
-    const physics = StretchingSheetPhysics(
+    const physics = BouncingSheetPhysics(
       parent: SnappingSheetPhysics(),
     );
 

cookbook/lib/tutorial/sheet_physics.dart

@@ -18,9 +18,9 @@ class _SheetPhysicsExample extends StatelessWidget {
 
 enum _PhysicsKind {
   clamping('Clamping'),
-  stretching('Stretching'),
+  bouncing('Bouncing'),
   clampingSnapping('Clamping + Snapping'),
-  stretchingSnapping('Stretching + Snapping');
+  bouncingSnapping('Bouncing + Snapping');
 
   final String name;
 
@@ -35,7 +35,7 @@ class _ExampleHome extends StatefulWidget {
 }
 
 class _ExampleHomeState extends State<_ExampleHome> {
-  _PhysicsKind selectedPhysics = _PhysicsKind.stretchingSnapping;
+  _PhysicsKind selectedPhysics = _PhysicsKind.bouncingSnapping;
 
   @override
   Widget build(BuildContext context) {
@@ -101,12 +101,12 @@ class _MySheet extends StatelessWidget {
 
     return switch (kind) {
       _PhysicsKind.clamping => const ClampingSheetPhysics(),
-      _PhysicsKind.stretching => const StretchingSheetPhysics(),
+      _PhysicsKind.bouncing => const BouncingSheetPhysics(),
       _PhysicsKind.clampingSnapping =>
         // Use 'parent' to combine multiple physics behaviors.
         ClampingSheetPhysics(parent: snappingPhysics),
-      _PhysicsKind.stretchingSnapping =>
-        StretchingSheetPhysics(parent: snappingPhysics),
+      _PhysicsKind.bouncingSnapping =>
+        BouncingSheetPhysics(parent: snappingPhysics),
     };
   }
 

docs/migration-guide-0.8.x.md

@@ -4,9 +4,13 @@ Here is the summary of the breaking changes included in the version 0.8.0.
 
 ## Changes in StretchingSheetPhysics
 
-### New way to control the stretching behavior of a sheet
+### 'Stretching' was renamed to 'Bouncing'
 
-[StretchingSheetBehavior](https://pub.dev/documentation/smooth_sheets/latest/smooth_sheets/StretchingSheetBehavior-class.html) was added as the new way to control the stretching behavior of a sheet. It replaces `StretchingSheetPhysics.stretchingRange` property, which has been removed.
+`StretchingSheetPhysics` was renamed to `BouncingSheetPhysics` to better reflect its behavior, as it does not change the actual size of the sheet, but rather allows the sheet position to go beyond the content bounds. Accordingly, the other related classes and properties were also renamed.
+
+### New way to control the bouncing behavior of a sheet
+
+[BouncingSheetBehavior](https://pub.dev/documentation/smooth_sheets/latest/smooth_sheets/BouncingSheetBehavior-class.html) was added as the new way to control the stretching behavior of a sheet. It replaces `StretchingSheetPhysics.stretchingRange` property, which has been removed.
 
 **BEFORE:**
 
@@ -19,12 +23,12 @@ const physics = StretchingSheetPhysics(
 **AFTER:**
 
 ```dart
-const physics = StretchingSheetPhysics(
-  behavior: FixedStretchingBehavior(Extent.proportional(0.1)),
+const physics = BouncingSheetPhysics(
+  behavior: FixedBouncingBehavior(Extent.proportional(0.1)),
 );
 ```
 
 See also:
 
-- [FixedStretchingBehavior](https://pub.dev/documentation/smooth_sheets/latest/smooth_sheets/FixedStretchingBehavior-class.html), which stretches the sheet by a fixed amount.
-- [DirectionAwareStretchingBehavior](https://pub.dev/documentation/smooth_sheets/latest/smooth_sheets/DirectionAwareStretchingBehavior-class.html), which stretches the sheet by a fixed amount, based on the direction of a drag.
+- [FixedBouncingBehavior](https://pub.dev/documentation/smooth_sheets/latest/smooth_sheets/FixedBouncingBehavior-class.html), which stretches the sheet by a fixed amount.
+- [DirectionAwareBouncingBehavior](https://pub.dev/documentation/smooth_sheets/latest/smooth_sheets/DirectionAwareBouncingBehavior-class.html), which stretches the sheet by a fixed amount, based on the direction of a drag.

package/README.md

@@ -221,10 +221,10 @@ See also:
 A physics determines how the sheet will behave when over-dragged or under-dragged, or when the user stops dragging. There are 3 predefined physics:
 
 - ClampingSheetPhysics: Prevents the sheet from reaching beyond the draggable bounds
-- StretchingSheetPhysics: Allows the sheet to go beyond the draggable bounds, but then bounce the sheet back to the edge of those bounds
+- BouncingSheetPhysics: Allows the sheet to go beyond the draggable bounds, but then bounce the sheet back to the edge of those bounds
 - SnappingSheetPhysics: Automatically snaps the sheet to a certain extent when the user stops dragging
 
-These physics can be combined to create more complex behavior (e.g. stretching behavior + snapping behavior).
+These physics can be combined to create more complex behavior (e.g. bouncing behavior + snapping behavior).
 
 
 

package/lib/src/foundation/foundation.dart

@@ -34,18 +34,18 @@ export 'sheet_notification.dart'
         SheetUpdateNotification;
 export 'sheet_physics.dart'
     show
+        BouncingBehavior,
+        BouncingSheetPhysics,
         ClampingSheetPhysics,
-        DirectionAwareStretchingBehavior,
-        FixedStretchingBehavior,
+        DirectionAwareBouncingBehavior,
+        FixedBouncingBehavior,
         InterpolationSimulation,
         SheetPhysics,
         SheetPhysicsMixin,
         SnapToNearest,
         SnapToNearestEdge,
         SnappingSheetBehavior,
         SnappingSheetPhysics,
-        StretchingBehavior,
-        StretchingSheetPhysics,
         kDefaultSheetPhysics,
         kDefaultSheetSpring;
 export 'sheet_status.dart' show SheetStatus;

package/lib/src/foundation/sheet_physics.dart

@@ -26,7 +26,7 @@ const _kDefaultSettlingSpeed = 600.0; // logical pixels per second
 
 /// The default [SheetPhysics] used by sheet widgets.
 const kDefaultSheetPhysics =
-    StretchingSheetPhysics(parent: SnappingSheetPhysics());
+    BouncingSheetPhysics(parent: SnappingSheetPhysics());
 
 // TODO: Implement `equals` and `hashCode` for SheetPhysics classes.
 abstract class SheetPhysics {
@@ -378,80 +378,88 @@ class ClampingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
   }
 }
 
-/// An object that determines the behavior of a sheet when it is out of bounds.
+/// {@template BouncingBehavior}
+/// An object that determines the behavior of a bounceable sheet
+/// when it is out of the content bounds.
+/// {@endtemplate}
 ///
 /// See also:
-/// - [FixedStretchingBehavior], which stretches the sheet by a fixed amount.
-/// - [DirectionAwareStretchingBehavior], which stretches the sheet based on the
-///   direction of a drag.
-abstract class StretchingBehavior {
-  /// Returns the number of pixels the sheet can stretch beyond the content
-  /// bounds.
+/// - [FixedBouncingBehavior], which allows the sheet position to exceed the
+///   content bounds by a fixed amount.
+/// - [DirectionAwareBouncingBehavior], which allows the sheet position to
+///  exceed the content bounds by different amounts based on the direction
+///  of a drag gesture.
+abstract class BouncingBehavior {
+  /// Returns the number of pixels that the sheet position can go beyond
+  /// the content bounds.
   ///
-  /// [StretchingSheetPhysics.applyPhysicsToOffset] calls this method to
-  /// determine how many pixels the sheet can stretch beyond the content bounds.
-  /// The returned value must be non-negative.
+  /// [BouncingSheetPhysics.applyPhysicsToOffset] calls this method to calculate
+  /// the amount of friction that should be applied to the given drag [offset].
   ///
-  /// The [offset] is the amount of pixels that will be applied to the sheet,
-  /// and [metrics] is the current metrics of the sheet.
-  double computeStretchablePixels(double offset, SheetMetrics metrics);
+  /// The returned value must be non-negative. Since this method may be called
+  /// every frame, and even multiple times per frame, it is not recommended to
+  /// return different values for each call, as it may cause unstable motion.
+  double computeBounceablePixels(double offset, SheetMetrics metrics);
 }
 
-/// A [StretchingBehavior] that stretches the sheet by a fixed amount.
+/// A [BouncingBehavior] that allows the sheet position to exceed the content
+/// bounds by a fixed amount.
+///
+/// The following is an example of a [BouncingSheetPhysics] that allows the
+/// sheet position to go beyond the [SheetMetrics.maxPixels] or
+/// [SheetMetrics.minPixels] by 12% of the content size.
 ///
-/// The following is an example of a [StretchingSheetPhysics] that allows the
-/// sheet to stretch by 12% of the content size.
 /// ```dart
-/// const physics = StretchingSheetPhysics(
-///   behavior: FixedStretchingBehavior(Extent.proportional(0.12)),
+/// const physics = BouncingSheetPhysics(
+///   behavior: FixedBouncingBehavior(Extent.proportional(0.12)),
 /// );
 /// ```
-class FixedStretchingBehavior implements StretchingBehavior {
-  /// Creates a [StretchingBehavior] that stretches the sheet by a fixed amount.
-  const FixedStretchingBehavior(this.range);
+class FixedBouncingBehavior implements BouncingBehavior {
+  /// Creates a [BouncingBehavior] that allows the sheet to bounce by a fixed
+  /// amount.
+  const FixedBouncingBehavior(this.range);
 
-  /// How much the sheet can stretch beyond the content bounds.
+  /// How much the sheet can bounce beyond the content bounds.
   final Extent range;
 
   @override
-  double computeStretchablePixels(double offset, SheetMetrics metrics) {
+  double computeBounceablePixels(double offset, SheetMetrics metrics) {
     return range.resolve(metrics.contentSize);
   }
 }
 
-/// A [StretchingBehavior] that stretches the sheet by a fixed amount.
+/// A [BouncingBehavior] that allows the sheet position to exceed the content
+/// bounds by different amounts based on the direction of a drag gesture.
 ///
-/// Different stretching ranges can be specified for upward and downward
-/// directions. For example, the following [StretchingSheetPhysics] allows the
-/// sheet to stretch by 12% of the content size when dragged downward, and by
+/// Different bounceable amounts can be specified for upward and downward
+/// directions. For example, the following [BouncingSheetPhysics] allows the
+/// sheet to bounce by 12% of the content size when dragged downward, and by
 /// 8 pixels when dragged upward.
 ///
 /// ```dart
-/// const physics = StretchingSheetPhysics(
-///   behavior: DirectionAwareStretchingBehavior(
+/// const physics = BouncingSheetPhysics(
+///   behavior: DirectionAwareBouncingBehavior(
 ///     upward: Extent.pixels(8),
 ///     downward: Extent.proportional(0.12),
 ///   ),
 /// );
 /// ```
-class DirectionAwareStretchingBehavior implements StretchingBehavior {
-  /// Creates a [StretchingBehavior] that stretches the sheet by a fixed amount
-  /// based on the direction of a drag.
-  const DirectionAwareStretchingBehavior({
+class DirectionAwareBouncingBehavior implements BouncingBehavior {
+  /// Creates a [BouncingBehavior] that allows the sheet to bounce by different
+  /// amounts based on the direction of a drag gesture.
+  const DirectionAwareBouncingBehavior({
     this.upward = const Extent.pixels(0),
     this.downward = const Extent.pixels(0),
   });
 
-  /// How much the sheet can stretch beyond the content bounds when dragged
-  /// upward.
+  /// Amount of bounceable pixels when dragged upward.
   final Extent upward;
 
-  /// How much the sheet can stretch beyond the content bounds when dragged
-  /// downward.
+  /// Amount of bounceable pixels when dragged downward.
   final Extent downward;
 
   @override
-  double computeStretchablePixels(double offset, SheetMetrics metrics) {
+  double computeBounceablePixels(double offset, SheetMetrics metrics) {
     return switch (offset) {
       > 0.0 => upward.resolve(metrics.contentSize),
       < 0.0 => downward.resolve(metrics.contentSize),
@@ -460,17 +468,16 @@ class DirectionAwareStretchingBehavior implements StretchingBehavior {
   }
 }
 
-class StretchingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
-  const StretchingSheetPhysics({
+class BouncingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
+  const BouncingSheetPhysics({
     super.parent,
-    this.behavior = const FixedStretchingBehavior(Extent.proportional(0.12)),
+    this.behavior = const FixedBouncingBehavior(Extent.proportional(0.12)),
     this.frictionCurve = Curves.easeOutSine,
     this.spring = kDefaultSheetSpring,
   });
 
-  /// The behavior that determines how the sheet stretches when it is
-  /// out of the content bounds.
-  final StretchingBehavior behavior;
+  /// {@macro BouncingBehavior}
+  final BouncingBehavior behavior;
 
   final Curve frictionCurve;
 
@@ -481,11 +488,10 @@ class StretchingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
   SheetPhysics copyWith({
     SheetPhysics? parent,
     SpringDescription? spring,
-    Extent? stretchingRange,
-    StretchingBehavior? behavior,
+    BouncingBehavior? behavior,
     Curve? frictionCurve,
   }) {
-    return StretchingSheetPhysics(
+    return BouncingSheetPhysics(
       parent: parent ?? this.parent,
       spring: spring ?? this.spring,
       behavior: behavior ?? this.behavior,
@@ -495,8 +501,8 @@ class StretchingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
 
   @override
   double computeOverflow(double offset, SheetMetrics metrics) {
-    final stretchingRange = behavior.computeStretchablePixels(offset, metrics);
-    if (stretchingRange != 0) {
+    final bounceableRange = behavior.computeBounceablePixels(offset, metrics);
+    if (bounceableRange != 0) {
       return const ClampingSheetPhysics().applyPhysicsToOffset(offset, metrics);
     }
 
@@ -505,8 +511,8 @@ class StretchingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
 
   @override
   double applyPhysicsToOffset(double offset, SheetMetrics metrics) {
-    final stretchingRange = behavior.computeStretchablePixels(offset, metrics);
-    if (stretchingRange == 0) {
+    final bounceableRange = behavior.computeBounceablePixels(offset, metrics);
+    if (bounceableRange == 0) {
       return const ClampingSheetPhysics().applyPhysicsToOffset(offset, metrics);
     }
 
@@ -535,7 +541,7 @@ class StretchingSheetPhysics extends SheetPhysics with SheetPhysicsMixin {
       final overflowPastStart = max(minPixels - currentPixels, 0.0);
       final overflowPastEnd = max(currentPixels - maxPixels, 0.0);
       final overflowPast = max(overflowPastStart, overflowPastEnd);
-      final overflowFraction = (overflowPast / stretchingRange).clampAbs(1);
+      final overflowFraction = (overflowPast / bounceableRange).clampAbs(1);
       final frictionFactor = frictionCurve.transform(overflowFraction);
 
       newPixels += fragment * (1.0 - frictionFactor);