Animations package improvements (#3796)

## Follow up for #3639

<!-- Add a brief overview here of the feature/bug & fix. -->

## PR Type
What kind of change does this PR introduce?
<!-- Please uncomment one or more that apply to this PR. -->

- Feature
- Improvements
<!-- - Code style update (formatting) -->
<!-- - Refactoring (no functional changes, no api changes) -->
<!-- - Build or CI related changes -->
<!-- - Documentation content changes -->
<!-- - Sample app changes -->
<!-- - Other... Please describe: -->


## Changelog

This PR tracks new changes and tweaks for the `Microsoft.Toolkit.Uwp.UI.Animations` package before the 7.0 release.
Changes are done according to feedbacks and requests from developers trying out the Preview 5 release.
This PR contains the following changes:

- All `AnimationBuilder` and XAML animation types now use `AnimationDelayBehavior.SetValueBeforeDelay` by default
- New `DelayBehavior` property available for XAML animation types (ignored when an animation is on the XAML layer)
- New `delayBehavior` parameter available for the explicit `AnimationBuilder` keyframe animation APIs (the more advanced ones)
- New `RepeatOption` parameter now available for all `AnimationBuilder` APIs (default, keyframe, etc.)

Opening as a draft PR until we finalize the list of changes to add.

## PR Checklist

Please check if your PR fulfills the following requirements:

- [X] Tested code with current [supported SDKs](../readme.md#supported)
- [ ] Pull Request has been submitted to the documentation repository [instructions](..\contributing.md#docs). Link: <!-- docs PR link -->
- [ ] Sample in sample app has been added / updated (for bug fixes / features)
    - [ ] Icon has been created (if new sample) following the [Thumbnail Style Guide and templates](https://github.com/windows-toolkit/WindowsCommunityToolkit-design-assets)
- [X] New major technical changes in the toolkit have or will be added to the [Wiki](https://github.com/windows-toolkit/WindowsCommunityToolkit/wiki) e.g. build changes, source generators, testing infrastructure, sample creation changes, etc...
- [ ] Tests for the changes have been added (for bug fixes / features) (if applicable)
- [X] Header has been added to all new source files (run *build/UpdateHeaders.bat*)
- [ ] Contains **NO** breaking changes

Author: msftbot[bot]

Microsoft.Toolkit.Uwp.UI.Animations/Builders/AnimationBuilder.Default.cs

@@ -61,6 +61,7 @@ private sealed record AnimationFactory<T>(
             T? From,
             TimeSpan Delay,
             TimeSpan Duration,
+            RepeatOption Repeat,
             EasingType EasingType,
             EasingMode EasingMode)
             : ICompositionAnimationFactory, IXamlAnimationFactory
@@ -70,6 +71,7 @@ private sealed record AnimationFactory<T>(
             public CompositionAnimation GetAnimation(CompositionObject targetHint, out CompositionObject? target)
             {
                 CompositionEasingFunction? easingFunction = targetHint.Compositor.TryCreateEasingFunction(EasingType, EasingMode);
+                (AnimationIterationBehavior iterationBehavior, int iterationCount) = Repeat.ToBehaviorAndCount();
 
                 target = null;
 
@@ -80,7 +82,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetToAs<bool>(),
                         GetFromAs<bool>(),
                         Delay,
-                        Duration);
+                        Duration,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(float))
@@ -91,7 +95,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetFromAs<float>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(double))
@@ -102,7 +108,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         (float?)GetFromAs<double>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(Vector2))
@@ -113,7 +121,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetFromAs<Vector2>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(Vector3))
@@ -124,7 +134,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetFromAs<Vector3>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(Vector4))
@@ -135,7 +147,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetFromAs<Vector4>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(Color))
@@ -146,7 +160,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetFromAs<Color>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 if (typeof(T) == typeof(Quaternion))
@@ -157,7 +173,9 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                         GetFromAs<Quaternion>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        iterationBehavior: iterationBehavior,
+                        iterationCount: iterationCount);
                 }
 
                 throw new InvalidOperationException("Invalid animation type");
@@ -177,6 +195,7 @@ public Timeline GetAnimation(DependencyObject targetHint)
                         Delay,
                         Duration,
                         easingFunction,
+                        Repeat.ToRepeatBehavior(),
                         enableDependecyAnimations: true);
                 }
 
@@ -189,6 +208,7 @@ public Timeline GetAnimation(DependencyObject targetHint)
                         Delay,
                         Duration,
                         easingFunction,
+                        Repeat.ToRepeatBehavior(),
                         enableDependecyAnimations: true);
                 }
 
@@ -201,6 +221,7 @@ public Timeline GetAnimation(DependencyObject targetHint)
                         Delay,
                         Duration,
                         easingFunction,
+                        Repeat.ToRepeatBehavior(),
                         enableDependecyAnimations: true);
                 }
 
@@ -212,7 +233,8 @@ public Timeline GetAnimation(DependencyObject targetHint)
                         GetFromAs<Color>(),
                         Delay,
                         Duration,
-                        easingFunction);
+                        easingFunction,
+                        Repeat.ToRepeatBehavior());
                 }
 
                 throw new InvalidOperationException("Invalid animation type");
@@ -287,6 +309,7 @@ private sealed record CompositionClipScalarAnimation(
             float? From,
             TimeSpan Delay,
             TimeSpan Duration,
+            RepeatOption Repeat,
             EasingType EasingType,
             EasingMode EasingMode)
             : ICompositionAnimationFactory
@@ -297,7 +320,16 @@ public CompositionAnimation GetAnimation(CompositionObject targetHint, out Compo
                 Visual visual = (Visual)targetHint;
                 InsetClip clip = visual.Clip as InsetClip ?? (InsetClip)(visual.Clip = visual.Compositor.CreateInsetClip());
                 CompositionEasingFunction? easingFunction = clip.Compositor.TryCreateEasingFunction(EasingType, EasingMode);
-                ScalarKeyFrameAnimation animation = clip.Compositor.CreateScalarKeyFrameAnimation(Property, To, From, Delay, Duration, easingFunction);
+                (AnimationIterationBehavior iterationBehavior, int iterationCount) = Repeat.ToBehaviorAndCount();
+                ScalarKeyFrameAnimation animation = clip.Compositor.CreateScalarKeyFrameAnimation(
+                    Property,
+                    To,
+                    From,
+                    Delay,
+                    Duration,
+                    easingFunction,
+                    iterationBehavior: iterationBehavior,
+                    iterationCount: iterationCount);
 
                 target = clip;
 
@@ -314,6 +346,7 @@ private sealed record XamlTransformDoubleAnimationFactory(
             double? From,
             TimeSpan Delay,
             TimeSpan Duration,
+            RepeatOption Repeat,
             EasingType EasingType,
             EasingMode EasingMode)
             : IXamlAnimationFactory
@@ -328,7 +361,14 @@ public Timeline GetAnimation(DependencyObject targetHint)
                     element.RenderTransform = transform = new CompositeTransform();
                 }
 
-                return transform.CreateDoubleAnimation(Property, To, From, Duration, Delay, EasingType.ToEasingFunction(EasingMode));
+                return transform.CreateDoubleAnimation(
+                    Property,
+                    To,
+                    From,
+                    Duration,
+                    Delay,
+                    EasingType.ToEasingFunction(EasingMode),
+                    Repeat.ToRepeatBehavior());
             }
         }
 

Microsoft.Toolkit.Uwp.UI.Animations/Builders/AnimationBuilder.Factories.cs

@@ -236,6 +236,7 @@ public IPropertyAnimationBuilder<Vector2> Size()
         /// <param name="delay">The optional initial delay for the animation.</param>
         /// <param name="duration">The animation duration.</param>
         /// <param name="repeatOption">The repeat option for the animation (defaults to one iteration).</param>
+        /// <param name="delayBehavior">The delay behavior to use (ignored if <paramref name="layer"/> is <see cref="FrameworkLayer.Xaml"/>).</param>
         /// <param name="layer">The target framework layer to animate.</param>
         /// <returns>The current <see cref="AnimationBuilder"/> instance.</returns>
         public AnimationBuilder NormalizedKeyFrames<T>(
@@ -244,6 +245,7 @@ public AnimationBuilder NormalizedKeyFrames<T>(
             TimeSpan? delay = null,
             TimeSpan? duration = null,
             RepeatOption? repeatOption = null,
+            AnimationDelayBehavior? delayBehavior = null,
             FrameworkLayer layer = FrameworkLayer.Composition)
             where T : unmanaged
         {
@@ -253,7 +255,8 @@ public AnimationBuilder NormalizedKeyFrames<T>(
                     property,
                     delay,
                     duration ?? DefaultDuration,
-                    repeatOption ?? RepeatOption.Once);
+                    repeatOption ?? RepeatOption.Once,
+                    delayBehavior ?? DefaultDelayBehavior);
 
                 build(builder);
 
@@ -286,6 +289,7 @@ public AnimationBuilder NormalizedKeyFrames<T>(
         /// <param name="delay">The optional initial delay for the animation.</param>
         /// <param name="duration">The animation duration.</param>
         /// <param name="repeatOption">The repeat option for the animation (defaults to one iteration).</param>
+        /// <param name="delayBehavior">The delay behavior to use (ignored if <paramref name="layer"/> is <see cref="FrameworkLayer.Xaml"/>).</param>
         /// <param name="layer">The target framework layer to animate.</param>
         /// <returns>The current <see cref="AnimationBuilder"/> instance.</returns>
         public AnimationBuilder NormalizedKeyFrames<T, TState>(
@@ -295,6 +299,7 @@ public AnimationBuilder NormalizedKeyFrames<T, TState>(
             TimeSpan? delay = null,
             TimeSpan? duration = null,
             RepeatOption? repeatOption = null,
+            AnimationDelayBehavior? delayBehavior = null,
             FrameworkLayer layer = FrameworkLayer.Composition)
             where T : unmanaged
         {
@@ -304,7 +309,8 @@ public AnimationBuilder NormalizedKeyFrames<T, TState>(
                     property,
                     delay,
                     duration ?? DefaultDuration,
-                    repeatOption ?? RepeatOption.Once);
+                    repeatOption ?? RepeatOption.Once,
+                    delayBehavior ?? DefaultDelayBehavior);
 
                 build(builder, state);
 
@@ -334,19 +340,25 @@ public AnimationBuilder NormalizedKeyFrames<T, TState>(
         /// <param name="build">The callback to use to construct the custom animation.</param>
         /// <param name="delay">The optional initial delay for the animation.</param>
         /// <param name="repeat">The repeat option for the animation (defaults to one iteration).</param>
+        /// <param name="delayBehavior">The delay behavior to use (ignored if <paramref name="layer"/> is <see cref="FrameworkLayer.Xaml"/>).</param>
         /// <param name="layer">The target framework layer to animate.</param>
         /// <returns>The current <see cref="AnimationBuilder"/> instance.</returns>
         public AnimationBuilder TimedKeyFrames<T>(
             string property,
             Action<ITimedKeyFrameAnimationBuilder<T>> build,
             TimeSpan? delay = null,
             RepeatOption? repeat = null,
+            AnimationDelayBehavior? delayBehavior = null,
             FrameworkLayer layer = FrameworkLayer.Composition)
             where T : unmanaged
         {
             if (layer == FrameworkLayer.Composition)
             {
-                TimedKeyFrameAnimationBuilder<T>.Composition builder = new(property, delay, repeat ?? RepeatOption.Once);
+                TimedKeyFrameAnimationBuilder<T>.Composition builder = new(
+                    property,
+                    delay,
+                    repeat ?? RepeatOption.Once,
+                    delayBehavior ?? DefaultDelayBehavior);
 
                 build(builder);
 
@@ -374,6 +386,7 @@ public AnimationBuilder TimedKeyFrames<T>(
         /// <param name="build">The callback to use to construct the custom animation.</param>
         /// <param name="delay">The optional initial delay for the animation.</param>
         /// <param name="repeatOption">The repeat option for the animation (defaults to one iteration).</param>
+        /// <param name="delayBehavior">The delay behavior to use (ignored if <paramref name="layer"/> is <see cref="FrameworkLayer.Xaml"/>).</param>
         /// <param name="layer">The target framework layer to animate.</param>
         /// <returns>The current <see cref="AnimationBuilder"/> instance.</returns>
         public AnimationBuilder TimedKeyFrames<T, TState>(
@@ -382,12 +395,17 @@ public AnimationBuilder TimedKeyFrames<T, TState>(
             Action<ITimedKeyFrameAnimationBuilder<T>, TState> build,
             TimeSpan? delay = null,
             RepeatOption? repeatOption = null,
+            AnimationDelayBehavior? delayBehavior = null,
             FrameworkLayer layer = FrameworkLayer.Composition)
             where T : unmanaged
         {
             if (layer == FrameworkLayer.Composition)
             {
-                TimedKeyFrameAnimationBuilder<T>.Composition builder = new(property, delay, repeatOption ?? RepeatOption.Once);
+                TimedKeyFrameAnimationBuilder<T>.Composition builder = new(
+                    property,
+                    delay,
+                    repeatOption ?? RepeatOption.Once,
+                    delayBehavior ?? DefaultDelayBehavior);
 
                 build(builder, state);