StateContainer, Add ChangeStateWithAnimation()

[VladislavAntonyuk]

Description of Change

Instead of throwing exceptions, just return. The animation operation is canceled but we still can continue going to the next state.

Linked Issues

• Fixes [BUG] StateContainer crash app when state change too fast  #942, [Proposal] Create StateContainer.ChangeStateWithAnimation() API #1027

PR Checklist

• Has a linked Issue, and the Issue has been approved(bug) or Championed (feature/proposal)
• Has tests (if omitted, state reason in description)
• Has samples (if omitted, state reason in description)
• Rebased on top of main at time of PR
• Changes adhere to coding standard
• Documentation created or updated: StateContainer new api MicrosoftDocs/CommunityToolkit#235

Additional information

[brminnick]

Hey Vlad! The experience described in the Issue is the expected behavior.

We added CanStateChange and documented how to use it in the docs to avoid this Exception:

https://learn.microsoft.com/dotnet/communitytoolkit/maui/layouts/statecontainer#viewmodel

[brminnick]

The fix for #942 should be specific to resizing the Window on WinUI and not remove the StateContainerException in its entirety.

[brminnick]

Thanks Vlad!

I added some tests to ensure/verify that the user can't change CurrentState while the animations are running.

Check out the code I added to ensure it looks good.

I'll approve this, and if you think it looks good, you can go ahead and merge it 🙌

[brminnick]

@bijington Are you able to help update the docs for this PR? I've added do not merge Do not merge this PR and pending documentation This feature requires documentation for now to ensure we update the docs.

Removed APIs

StateContainer.ShouldAnimateOnStateChangeProperty

Added APIs

/// <summary>
/// Change state with custom animation.
/// </summary>
public static async Task ChangeStateWithAnimation(
 		BindableObject bindable,
 		string? state,
 		Animation? beforeStateChange,
 		Animation? afterStateChange,
 		CancellationToken token);

/// <summary>
/// Change state with custom animation.
/// </summary>
public static async Task ChangeStateWithAnimation(
 		BindableObject bindable,
 		string? state,
 		Func<VisualElement, CancellationToken, Task>? beforeStateChange,
 		Func<VisualElement, CancellationToken, Task>? afterStateChange,
 		CancellationToken cancellationToken);

/// <summary>
/// Change state using the default fade animation.
/// </summary>
public static async Task ChangeStateWithAnimation(BindableObject bindable, string? state, CancellationToken token);

[brminnick]

Removed APIs

^ FYI @jfversluis This is a breaking change that we'll need to note in the release notes for v5.0.0

[VladislavAntonyuk]

@brminnick , @bijington new docs: MicrosoftDocs/CommunityToolkit#235

[Strypper]

Thanks guys really appreciate your work.