docs: add feature list and categories (#20)

packages/fleet/README.md

@@ -4,8 +4,22 @@
 > ⚠️ This package is in an early state of development. If you find any bugs or
 > have any suggestions, please open an [issue][issues].
 
-**Fleet** is an animation framework that animates state changes instead of
-individual values.
+**Fleet** is an animation framework for Flutter.
+
+- [**State-based**][animated]: Animate all visual changes that are the result of
+  a state change.
+- [**Declarative**][animationspec]: Describe an animation and apply it to a
+  state change. No need to manage `AnimationController`s or `Tween`s.
+- **Animatable widgets**: Comes out of the box with general purpose widgets that
+  support animating with Fleet.
+  - [**Extensible**][animatablestatemixin]: Any widget can be made to support
+    animating with Fleet.
+  - **Flexible**: Animatable widgets can be used with or without animations.
+  - **Composable**: Widgets that build on animatable widgets are automatically
+    animatable.
+  - **Animate parameters individually**: Animate parameters of animatable widget
+    individually, e.g. with different curves.
+- **User-friendly**: Add and change animations with little refactoring.
 
 # Getting started
 
@@ -92,7 +106,7 @@ Now lets animate the state change of `_active`:
      return GestureDetector(
        onTap: () {
 -        setState(() {
-+        setStateWithAnimation(const AnimationSpec(), () {
++        setStateWithAnimation(Curves.ease.animation(250.ms), () {
            _active = !_active;
          });
        },
@@ -125,10 +139,15 @@ immediately executed like it is the case for `setState`. Instead, it is executed
 as part of building the next frame. In practice this seldomly makes a
 difference.
 
-The [`AnimationSpec`][animationspec] that we pass to `setStateWithAnimation`
-specifies how to animate from the old to the new state. `const AnimationSpec()`
-is the default animation spec, which uses `Curves.linear` and animates for
-200ms.
+`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.
+
+`.animate` is an extension method on `Curve` that creates an
+[`AnimationSpec`][animationspec] form the curve. It optionally takes a
+`Duration`. For a nicer syntax for specifying `Duration`s, Fleet provides
+extensions on `int`, e.g `250.ms` is equivalent to
+`Duration(milliseconds: 250)`.
 
 # Animatable widgets
 
@@ -152,6 +171,8 @@ 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
 [animatablestatemixin]:
@@ -160,3 +181,4 @@ for animating with Fleet:
   https://pub.dev/documentation/fleet/latest/fleet/AnimationSpec-class.html
 [acoloredbox]:
   https://pub.dev/documentation/fleet/latest/fleet/AColoredBox-class.html
+[animated]: https://pub.dev/documentation/fleet/latest/fleet/Animated-class.html

packages/fleet/dartdoc_options.yaml

@@ -0,0 +1,12 @@
+dartdoc:
+  categories:
+    'Animate':
+      markdown: doc/Animate.md
+    'Animatable widget':
+      markdown: doc/Animatable_widget.md
+    'Animatable Flutter widget':
+      markdown: doc/Animatable_Flutter_widget.md
+  categoryOrder:
+    - 'Animate'
+    - 'Animatable widget'
+    - 'Animatable Flutter widget'

packages/fleet/doc/Animatable_Flutter_widget.md

@@ -0,0 +1,2 @@
+Drop-in replacements for widgets from the Flutter framework that support
+animating with Fleet.

packages/fleet/doc/Animatable_widget.md

@@ -0,0 +1 @@
+Components which allow you tu build widgets that support animating with Fleet.

packages/fleet/doc/Animate.md

@@ -0,0 +1 @@
+APIs for describing animations and applying them to state changes.

packages/fleet/lib/fleet.dart

@@ -1,3 +1,5 @@
+export 'src/animatable_flutter_widgets.dart'
+    show AAlign, AColoredBox, AContainer, ASizedBox;
 export 'src/animatable_widget.dart'
     show
         AnimatableAlignmentGeometry,
@@ -23,8 +25,6 @@ export 'src/animatable_widget.dart'
         OptionalAnimatableMatrix4,
         OptionalAnimatableRect,
         OptionalAnimatableSize;
-export 'src/animatable_widgets.dart'
-    show AAlign, AColoredBox, AContainer, ASizedBox;
 export 'src/animate.dart'
     show Animated, FleetBinding, withAnimation, SetStateWithAnimationExtension;
 export 'src/animation.dart' show AnimationSpec, AnimationFromCurveExtension;

packages/fleet/lib/src/animatable_widgets.dart → packages/fleet/lib/src/animatable_flutter_widgets.dart

@@ -3,6 +3,8 @@ import 'package:flutter/widgets.dart';
 import 'animatable_widget.dart';
 
 /// Animatable version of [Align].
+///
+/// {@category Animatable Flutter widget}
 class AAlign extends StatefulWidget {
   /// Creates an animatable version of [Align].
   const AAlign({
@@ -62,6 +64,8 @@ class _AAlignState extends AnimatableState<AAlign> {
 }
 
 /// Animatable version of [ColoredBox].
+///
+/// {@category Animatable Flutter widget}
 class AColoredBox extends StatefulWidget {
   /// Creates an animatable version of [ColoredBox].
   const AColoredBox({super.key, required this.color, this.child});
@@ -94,6 +98,8 @@ class _AColoredBoxState extends AnimatableState<AColoredBox> {
 }
 
 /// Animatable version of [Container].
+///
+/// {@category Animatable Flutter widget}
 class AContainer extends StatefulWidget {
   /// Creates an animatable version of [Container].
   AContainer({
@@ -223,6 +229,8 @@ class _AContainerState extends AnimatableState<AContainer> {
 }
 
 /// Animatable version of [SizedBox].
+///
+/// {@category Animatable Flutter widget}
 class ASizedBox extends StatefulWidget {
   /// Creates an animatable version of [SizedBox].
   const ASizedBox({

packages/fleet/lib/src/animatable_widget.dart

@@ -15,6 +15,8 @@ import 'transaction.dart';
 ///
 /// An [AnimatableParameter] uses the [AnimationSpec] that is active when a new
 /// value is set to animate the change.
+///
+/// {@category Animatable widget}
 abstract class AnimatableParameter<T>
     with Diagnosticable
     implements AnimatableValue<T> {
@@ -153,6 +155,8 @@ class _OptionalTween<T> extends Tween<T?> {
 
 /// An [AnimatableParameter] that animates changes to an [AlignmentGeometry]
 /// through an [AlignmentGeometryTween].
+///
+/// {@category Animatable widget}
 class AnimatableAlignmentGeometry
     extends AnimatableParameter<AlignmentGeometry> {
   /// Creates an [AnimatableParameter] that animates changes to an
@@ -164,6 +168,8 @@ class AnimatableAlignmentGeometry
 }
 
 /// Version of [AnimatableAlignmentGeometry] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableAlignmentGeometry
     extends AnimatableParameter<AlignmentGeometry?> {
   /// Creates a version of [AnimatableAlignmentGeometry] for optional
@@ -177,6 +183,8 @@ class OptionalAnimatableAlignmentGeometry
 
 /// An [AnimatableParameter] that animates changes to a [BoxConstraints] through
 /// a [BoxConstraintsTween].
+///
+/// {@category Animatable widget}
 class AnimatableBoxConstraints extends AnimatableParameter<BoxConstraints> {
   /// Creates an [AnimatableParameter] that animates changes to a
   /// [BoxConstraints] through a [BoxConstraintsTween].
@@ -187,6 +195,8 @@ class AnimatableBoxConstraints extends AnimatableParameter<BoxConstraints> {
 }
 
 /// Version of [AnimatableBoxConstraints] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableBoxConstraints
     extends AnimatableParameter<BoxConstraints?> {
   /// Creates a version of [AnimatableBoxConstraints] for optional parameters.
@@ -197,6 +207,8 @@ class OptionalAnimatableBoxConstraints
 
 /// An [AnimatableParameter] that animates changes to a [Color] through a
 /// [ColorTween].
+///
+/// {@category Animatable widget}
 class AnimatableColor extends AnimatableParameter<Color> {
   /// Creates an [AnimatableParameter] that animates changes to a [Color]
   /// through a [ColorTween].
@@ -207,6 +219,8 @@ class AnimatableColor extends AnimatableParameter<Color> {
 }
 
 /// Version of [AnimatableColor] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableColor extends AnimatableParameter<Color?> {
   /// Creates a version of [AnimatableColor] for optional parameters.
   OptionalAnimatableColor(super.value, {required super.state});
@@ -217,6 +231,8 @@ class OptionalAnimatableColor extends AnimatableParameter<Color?> {
 
 /// An [AnimatableParameter] that animates changes to a [Decoration] through a
 /// [DecorationTween].
+///
+/// {@category Animatable widget}
 class AnimatableDecoration extends AnimatableParameter<Decoration> {
   /// Creates an [AnimatableParameter] that animates changes to a [Decoration]
   /// through a [DecorationTween].
@@ -227,6 +243,8 @@ class AnimatableDecoration extends AnimatableParameter<Decoration> {
 }
 
 /// Version of [AnimatableDecoration] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableDecoration extends AnimatableParameter<Decoration?> {
   /// Creates a version of [AnimatableDecoration] for optional parameters.
   OptionalAnimatableDecoration(super.value, {required super.state});
@@ -237,6 +255,8 @@ class OptionalAnimatableDecoration extends AnimatableParameter<Decoration?> {
 
 /// An [AnimatableParameter] that animates changes to a [double] through a
 /// [Tween].
+///
+/// {@category Animatable widget}
 class AnimatableDouble extends AnimatableParameter<double> {
   /// Creates an [AnimatableParameter] that animates changes to a [double]
   /// through a [Tween].
@@ -247,6 +267,8 @@ class AnimatableDouble extends AnimatableParameter<double> {
 }
 
 /// Version of [AnimatableDouble] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableDouble extends AnimatableParameter<double?> {
   /// Creates a version of [AnimatableDouble] for optional parameters.
   OptionalAnimatableDouble(super.value, {required super.state});
@@ -257,6 +279,8 @@ class OptionalAnimatableDouble extends AnimatableParameter<double?> {
 
 /// An [AnimatableParameter] that animates changes to an [EdgeInsetsGeometry]
 /// through an [EdgeInsetsGeometryTween].
+///
+/// {@category Animatable widget}
 class AnimatableEdgeInsetsGeometry
     extends AnimatableParameter<EdgeInsetsGeometry> {
   /// Creates an [AnimatableParameter] that animates changes to an
@@ -268,6 +292,8 @@ class AnimatableEdgeInsetsGeometry
 }
 
 /// Version of [AnimatableEdgeInsetsGeometry] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableEdgeInsetsGeometry
     extends AnimatableParameter<EdgeInsetsGeometry?> {
   /// Creates a version of [AnimatableEdgeInsetsGeometry] for optional
@@ -281,6 +307,8 @@ class OptionalAnimatableEdgeInsetsGeometry
 
 /// An [AnimatableParameter] that animates changes to an [int] through an
 /// [IntTween].
+///
+/// {@category Animatable widget}
 class AnimatableInt extends AnimatableParameter<int> {
   /// Creates an [AnimatableParameter] that animates changes to an [int] through
   /// an [IntTween].
@@ -291,6 +319,8 @@ class AnimatableInt extends AnimatableParameter<int> {
 }
 
 /// Version of [AnimatableInt] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableInt extends AnimatableParameter<int?> {
   /// Creates a version of [AnimatableInt] that for optional parameters.
   OptionalAnimatableInt(super.value, {required super.state});
@@ -301,6 +331,8 @@ class OptionalAnimatableInt extends AnimatableParameter<int?> {
 
 /// An [AnimatableParameter] that animates changes to a [Matrix4] through a
 /// [Matrix4Tween].
+///
+/// {@category Animatable widget}
 class AnimatableMatrix4 extends AnimatableParameter<Matrix4> {
   /// Creates an [AnimatableParameter] that animates changes to a [Matrix4]
   /// through a [Matrix4Tween].
@@ -311,6 +343,8 @@ class AnimatableMatrix4 extends AnimatableParameter<Matrix4> {
 }
 
 /// Version of [AnimatableMatrix4] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableMatrix4 extends AnimatableParameter<Matrix4?> {
   /// Creates a version of [AnimatableMatrix4] for optional parameters.
   OptionalAnimatableMatrix4(super.value, {required super.state});
@@ -321,6 +355,8 @@ class OptionalAnimatableMatrix4 extends AnimatableParameter<Matrix4?> {
 
 /// An [AnimatableParameter] that animates changes to a [Rect] through a
 /// [RectTween].
+///
+/// {@category Animatable widget}
 class AnimatableRect extends AnimatableParameter<Rect> {
   /// Creates an [AnimatableParameter] that animates changes to a [Rect] through
   /// a [RectTween].
@@ -331,6 +367,8 @@ class AnimatableRect extends AnimatableParameter<Rect> {
 }
 
 /// Version of [AnimatableRect] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableRect extends AnimatableParameter<Rect?> {
   /// Creates a version of [AnimatableRect] for optional parameters.
   OptionalAnimatableRect(super.value, {required super.state});
@@ -341,6 +379,8 @@ class OptionalAnimatableRect extends AnimatableParameter<Rect?> {
 
 /// An [AnimatableParameter] that animates changes to a [Size] through a
 /// [SizeTween].
+///
+/// {@category Animatable widget}
 class AnimatableSize extends AnimatableParameter<Size> {
   /// Creates an [AnimatableParameter] that animates changes to a [Size] through
   /// a [SizeTween].
@@ -351,6 +391,8 @@ class AnimatableSize extends AnimatableParameter<Size> {
 }
 
 /// Version of [AnimatableSize] for optional parameters.
+///
+/// {@category Animatable widget}
 class OptionalAnimatableSize extends AnimatableParameter<Size?> {
   /// Creates a version of [AnimatableSize] for optional parameters.
   OptionalAnimatableSize(super.value, {required super.state});
@@ -401,6 +443,8 @@ class OptionalAnimatableSize extends AnimatableParameter<Size?> {
 ///
 /// - [AnimatableState] for a [State] class that already mixes in
 ///   [AnimatableStateMixin] and [TickerProviderStateMixin].
+///
+/// {@category Animatable widget}
 mixin AnimatableStateMixin<T extends StatefulWidget>
     on State<T>, TickerProvider {
   final _parameters = <AnimatableParameter<void>>[];
@@ -448,5 +492,7 @@ mixin AnimatableStateMixin<T extends StatefulWidget>
 ///
 /// Extend your state class from this class instead of from [State], with
 /// [TickerProviderStateMixin] and [AnimatableStateMixin] mixed in.
+///
+/// {@category Animatable widget}
 abstract class AnimatableState<T extends StatefulWidget> extends State<T>
     with TickerProviderStateMixin, AnimatableStateMixin {}