Add a RepeatingAnimationBuilder API - #174014

Nit: I'd consider dropping this line - calling out something that's not present might confuse users.

Could you move the Ownership section up above the code samples?

This content mirrors but is slightly different from the "Ownership of the Tween" content on TweenAnimationBuilder. I'd consider making a template out of the original content and just use the template here.

https://github.com/flutter/flutter/blob/6cbd98adc517ca7a20c724c4f0c5a5a385b95f74/packages/flutter/lib/src/widgets/tween_animation_builder.dart#L58C1-L67C34

the issue of making a template (now) where it is a separate component is that I can't repeat "The [TweenAnimationBuilder] takes full ownership" unless it accepts variable so might make sense to repeat now :( or just omit or duplicate.

TweenAnimationBuilder.builder has type ValueWidgetBuilder<T> - should we use the same type here to be consistent?

This is tricky. ValueWidgetBuilder takes the actual value T, while RepeatingTweenAnimationBuilder is currently taking Animation.
The reason is, many examples require animation, so it doesn't make sense for us to do animation.value and then create a new FixedAnimation(value) or something like that, I thought it made more sense to just use animation directly instead of animation.value, but it makes it different than TweenAnimationBuilder, so it is tricky.

I wish Repeating had value instead of animation, but then it will make the code for example worse than right now. Any thoughts?

Examples like this would suffer:

TLDR: We should use ValueWidgetBuilder<T> here as well.

Whether the builder accepts a T or a Animation<T> has implications on how many times the builder should be called:

FooAnimationBuilder(
  tween: Tween<double>(begin: 0, end: 1),
  builder: (context, double sizeFactor, child) {
    // This builder is called each time sizeFactor changes.
    // The subtree is rebuilt on each tick.
    return ...;
  },
);

FooAnimationBuilder(
  tween: Tween<double>(begin: 0, end: 1),
  builder: (context, Animation<double> sizeFactorAnimation, child) {
    // This builder should be called ONCE. You or some child widget needs an
    // AnimatedBuilder to trigger a callback each time sizeFactorAnimation
    // changes. This lets you minimize the subtree that is rebuilt each
    // time the animation ticks.
    return ...;
  },
);

Since TweenAnimationBuilder uses the former pattern (T), RepeatingTweenAnimationBuilder should use the same pattern - it'd be confusing otherwise. I do think the latter pattern (Animation<T>) is something we should consider, however let's punt that until after this PR as I'd like to come up with a new naming convention that makes the distinction clear.

Counterintuitively, the AlwaysStoppedAnimation thing is a good thing. It's a code smell that indicates we're using some API incorrectly:

• Option 1: Switch to a child widget that doesn't accept an Animation<T>. For the SizeTransition example, we should consider switching to ClipRect + Align instead. For RotationTransition, we should consider switching to a Transform instead.
• Option 2: Consider whether the child widget actually needs to accept an Animation<T>. If the child widget rebuilds itself on each tick, it should might as well just accept a T.
• Option 3: Don't use RepeatingTweenAnimationBuilder. Go back to an explicit animation instead. Examples for this category: AnimatedIcon animations, FadeTransition animations (this has important optimizations over using Opacity directly), etc.

Let me know if you have any feedback or questions!

Can you document whether this means the duration is effectively doubled for each actual iteration, or that the curve is calculated at double speed?

(Alternatively we can document it in RepeatingAnimationBuilder or even in RepeatingAnimationBuilder.duration but I think documenting it here is more useful if this enum is to be used in other widgets. But feel free to do it this way if you find it easier.)

I drafted a suggestion below: https://github.com/flutter/flutter/pull/174014/files#r2519860585

FYI, this is needed because the first paragraph is what shows up in the IDE. The IDE tooltip is small, so for readability a single sentence is best.

Why is this needed?