TweenAnimationBuilder: Animate Anything Implicitly

WHY IT EXISTS TweenAnimationBuilder was created to provide a simple way to animate a single property of a widget without the boilerplate of creating and managing an AnimationController. It fills the gap between pre-built animated widgets, like AnimatedContainer, and fully manual animations that require an AnimatedBuilder and your own controller.

THE MENTAL MODEL Think of it as a "set it and forget it" animation widget. You give it a Tween (which defines the start and end values), a duration, and a curve. Whenever the end value of the Tween changes, the builder automatically animates from its current value to the new target. It handles the animation lifecycle for you.

HOW IT WORKS TweenAnimationBuilder is a stateful widget that internally manages its own AnimationController. When it first builds, it animates from the Tween.begin value to Tween.end. If you rebuild the widget with a new Tween that has a different end value, it triggers a new animation from the current value to the new end. Its builder function is called on every tick of the animation, providing the interpolated value which you use to build your widget.

WHEN TO USE IT Use it for simple, stateless animations on any widget property. For example, animating the size of an icon, changing a border color, or adjusting padding when a state variable changes. It's ideal when a pre-built widget like AnimatedOpacity doesn't exist for the property you want to animate.

WHEN NOT TO USE IT Don't use it if you need complex control over the animation, like pausing, reversing, or looping. For that, use an AnimatedBuilder and manage your own AnimationController. Also, if a specific ImplicitlyAnimatedWidget like AnimatedContainer already does what you need, prefer it for its simplicity.

ONE CANONICAL EXAMPLE A common use case is an IconButton that changes its size on press. You wrap the Icon in a TweenAnimationBuilder with a Tween<double> for the size. When the button is pressed, you update a state variable that determines the end value of the Tween. The builder automatically animates the size change. The main footgun is to not use the child parameter for parts of the UI that don't depend on the animation, which causes them to rebuild unnecessarily on every frame and hurts performance.