feat!: rename setStateWithAnimation to setStateWithAnimationAsync…

… and `withAnimation` to `withAnimationAsync` (#26)

This makes it clearer that the provided callback can be called asynchronously.

packages/fleet/README.md

@@ -105,7 +105,7 @@ Now lets animate the state change of `_active`:
      return GestureDetector(
        onTap: () {
 -        setState(() {
-+        setStateWithAnimation(Curves.ease.animation(250.ms), () {
++        setStateWithAnimationAsync(Curves.ease.animation(250.ms), () {
            _active = !_active;
          });
        },
@@ -119,7 +119,8 @@ Now lets animate the state change of `_active`:
 ```
 
 All we did was replace `ColoredBox` with [`AColoredBox`][acoloredbox] and use
-[`setStateWithAnimation`][setstatewithanimation] instead of `setState`.
+[`setStateWithAnimationAsync`][setstatewithanimationasync] instead of
+`setState`.
 
 The `AColoredBox` widget is a drop-in replacement for `ColoredBox` that supports
 animating with Fleet. Widgets that support animating with Fleet don't have any
@@ -132,22 +133,22 @@ state-based animation through components provided by Fleet (see
 [`AnimatableStateMixin`][animatablestatemixin]). Issues or PRs for adding
 support for more widgets are welcome!
 
-Note that we did not explicitly tell `setStateWithAnimation` what to animate.
-This is because Fleet uses a **state-based** approach. All state changes caused
-by executing the provided callback will be animated. Even the state changes
-which are indirect, like the `color` parameter of `AColoredBox` going from
-`Colors.grey` to `Colors.blue`. Fleet does this by tracking the state of
-animatable parameters of animatable widgets from one build to the next.
+Note that we did not explicitly tell `setStateWithAnimationAsync` what to
+animate. This is because Fleet uses a **state-based** approach. All state
+changes caused by executing the provided callback will be animated. Even the
+state changes which are indirect, like the `color` parameter of `AColoredBox`
+going from `Colors.grey` to `Colors.blue`. Fleet does this by tracking the state
+of animatable parameters of animatable widgets from one build to the next.
 
-`setStateWithAnimation` is a little bit special in that it does not immediately
-execute the callback, like it is the case for `setState`. Instead,
-`setStateWithAnimation` executes the callback as part of building the next
-frame. In practice this seldomly makes a difference. `setStateWithAnimation` is
-a method from an extension on `State`.
+`setStateWithAnimationAsync` is a little bit special in that it does not
+immediately execute the callback, like it is the case for `setState`. Instead,
+`setStateWithAnimationAsync` executes the callback as part of building the next
+frame. In practice this seldomly makes a difference.
+`setStateWithAnimationAsync` is a method from an extension on `State`.
 
 `Curves.ease.animation(250.ms)` creates an [`AnimationSpec`][animationspec] that
-we pass to `setStateWithAnimation` to specify how to animate from the old to the
-new state.
+we pass to `setStateWithAnimationAsync` to specify how to animate from the old
+to the new state.
 
 `.animate` is an extension method on `Curve` that creates an
 [`AnimationSpec`][animationspec] form the curve. It optionally takes a
@@ -184,10 +185,10 @@ for animating with Fleet:
   https://developer.apple.com/documentation/swiftui/animations
 [example_app]:
   https://github.com/blaugold/fleet/tree/main/packages/fleet/example
-[withanimation]:
-  https://pub.dev/documentation/fleet/latest/fleet/withAnimation.html
-[setstatewithanimation]:
-  https://pub.dev/documentation/fleet/latest/fleet/SetStateWithAnimationExtension/setStateWithAnimation.html
+[withanimationasync]:
+  https://pub.dev/documentation/fleet/latest/fleet/withAnimationAsync.html
+[setstatewithanimationasync]:
+  https://pub.dev/documentation/fleet/latest/fleet/SetStateWithAnimationExtension/setStateWithAnimationAsync.html
 [animatablestatemixin]:
   https://pub.dev/documentation/fleet/latest/fleet/AnimatableStateMixin-mixin.html
 [animationspec]:

packages/fleet/example/README.md

@@ -7,7 +7,7 @@ demonstrate the Fleet framework:
 - [simple_declarative_animation.dart] shows how to animate in a declarative
   style with `Animated`.
 - [simple_imperative_animation.dart] shows how to animate in an imperative style
-  with `setStateWithAnimation`.
+  with `setStateWithAnimationAsync`.
 - [stack.dart] shows how to stagger animations through `AnimatedSpec.delay`.
 
 [interactive_box_fleet.dart]:

packages/fleet/example/lib/interactive_box_fleet.dart

@@ -48,7 +48,7 @@ class _MyHomePageState extends State<MyHomePage> {
           });
         },
         onPanEnd: (_) {
-          setStateWithAnimation(Curves.ease.animation(300.ms), () {
+          setStateWithAnimationAsync(Curves.ease.animation(300.ms), () {
             _alignment = Alignment.center;
             _color = _distanceColorTween.begin!;
           });

packages/fleet/example/lib/simple_imperative_animation.dart

@@ -34,14 +34,14 @@ class _MyHomePageState extends State<MyHomePage> {
   var _size = _collapsedSize;
 
   void _collapse() {
-    setStateWithAnimation(Curves.easeInOut.animation(), () {
+    setStateWithAnimationAsync(Curves.easeInOut.animation(), () {
       _color = _collapsedColor;
       _size = _collapsedSize;
     });
   }
 
   void _expand() {
-    setStateWithAnimation(Curves.easeInOutExpo.animation(1.s), () {
+    setStateWithAnimationAsync(Curves.easeInOutExpo.animation(1.s), () {
       _color = _expandedColor;
       _size = (context.findRenderObject()! as RenderBox).size;
     });

packages/fleet/lib/fleet.dart

@@ -39,6 +39,10 @@ export 'src/animatable_widget.dart'
         OptionalAnimatableRect,
         OptionalAnimatableSize;
 export 'src/animate.dart'
-    show Animated, FleetBinding, withAnimation, SetStateWithAnimationExtension;
+    show
+        Animated,
+        FleetBinding,
+        withAnimationAsync,
+        SetStateWithAnimationExtension;
 export 'src/animation.dart' show AnimationSpec, AnimationFromCurveExtension;
 export 'src/duration.dart' show DurationFromIntExtension;

packages/fleet/lib/src/animate.dart

@@ -38,8 +38,8 @@ class FleetBinding extends BindingBase
 /// To apply an animation **only to state changes in a widget subtree**, see
 /// [Animated].
 ///
-/// See [SetStateWithAnimationExtension.setStateWithAnimation] for an extension
-/// method for animating state changes in a [StatefulWidget].
+/// See [SetStateWithAnimationExtension.setStateWithAnimationAsync] for an
+/// extension method for animating state changes in a [StatefulWidget].
 ///
 /// During the next frame, [block] will be called and all state changes that
 /// result from its execution will be animated with [animation].
@@ -60,7 +60,7 @@ class FleetBinding extends BindingBase
 ///   Widget build(BuildContext context) {
 ///     return GestureDetector(
 ///       onTap: () {
-///         withAnimation(Curves.ease.animation(250.ms), () {
+///         withAnimationAsync(Curves.ease.animation(250.ms), () {
 ///           active.value = !active.value;
 ///         });
 ///       },
@@ -77,13 +77,13 @@ class FleetBinding extends BindingBase
 ///
 /// See also:
 ///
-/// - [SetStateWithAnimationExtension.setStateWithAnimation] for animating state
-///   changes in a [StatefulWidget]'s [State].
+/// - [SetStateWithAnimationExtension.setStateWithAnimationAsync] for animating
+///   state changes in a [StatefulWidget]'s [State].
 /// - [Animated] for a widget that applies an [animation] to the state changes
 ///   in its descendants.
 ///
 /// {@category Animate}
-void withAnimation(AnimationSpec animation, void Function() block) {
+void withAnimationAsync(AnimationSpec animation, void Function() block) {
   final globalTransactionBinding = TransactionBinding.instance;
   if (globalTransactionBinding == null) {
     _debugWarnGlobalTransactionBindingIsNotInitialized();
@@ -101,7 +101,7 @@ void _debugWarnGlobalTransactionBindingIsNotInitialized() {
       _debugDidWarnGlobalTransactionsBindingIsNotInitialized = true;
       debugPrint(
         'GlobalTransactionBinding has not been initialized. Without it, '
-        'withAnimation, setStateWithAnimation and Animate cannot apply the '
+        'withAnimationAsync, setStateWithAnimationAsync and Animate cannot apply the '
         'provided animation. Make sure you have called '
         'FleetBinding.ensureInitialized() before runApp.',
       );
@@ -145,7 +145,7 @@ extension SetStateWithAnimationExtension on State {
   ///   Widget build(BuildContext context) {
   ///     return GestureDetector(
   ///       onTap: () {
-  ///         setStateWithAnimation(Curves.ease.animation(250.ms), () {
+  ///         setStateWithAnimationAsync(Curves.ease.animation(250.ms), () {
   ///           _active = !_active;
   ///         });
   ///       },
@@ -157,21 +157,24 @@ extension SetStateWithAnimationExtension on State {
   ///
   /// See also:
   ///
-  /// - [withAnimation] for a static function that works like this extension
-  ///   method, but without calling [State.setState].
+  /// - [withAnimationAsync] for a static function that works like this
+  ///   extension method, but without calling [State.setState].
   /// - [Animated] for a widget that applies an animation to the state changes
   ///   in its descendants.
   @protected
-  void setStateWithAnimation(AnimationSpec animation, void Function() block) {
+  void setStateWithAnimationAsync(
+    AnimationSpec animation,
+    void Function() block,
+  ) {
     // ignore: invalid_use_of_protected_member
-    withAnimation(animation, () => setState(block));
+    withAnimationAsync(animation, () => setState(block));
   }
 }
 
 /// A widget that applies an [animation] to state changes in its descendants.
 ///
-/// See [withAnimation] for a function that applies an animation to **all state
-/// changes that are the result of calling a callback**.
+/// See [withAnimationAsync] for a function that applies an animation to **all
+/// state changes that are the result of calling a callback**.
 ///
 /// {@template fleet.Animated.widgets}
 ///
@@ -240,7 +243,7 @@ extension SetStateWithAnimationExtension on State {
 ///
 /// See also:
 ///
-/// - [withAnimation] for a function that applies an animation to the state
+/// - [withAnimationAsync] for a function that applies an animation to the state
 ///   changes caused by calling a callback.
 ///
 /// {@category Animate}

packages/fleet/lib/src/animation.dart

@@ -21,7 +21,7 @@ import './animate.dart';
 /// - [speed]
 ///
 /// To apply an [AnimationSpec] to a state change, use [Animated],
-/// [withAnimation] or [SetStateWithAnimationExtension].
+/// [withAnimationAsync] or [SetStateWithAnimationExtension].
 ///
 /// ## Examples
 ///