Shell navigating deferral token

[PureWeen]

Description of Change

Provide a deferral token during navigating that users can use to invoke async operations

• Implementation uses the existing "cancel" behavior to "cancel" user initiated navigation. Once they complete the deferral then it uses GotoAsync to replay the navigation
• GotoAsync and all of the INavigation methods will not resolve until the user has completed all deferrals
• If user tries to navigate while there is a pending deferral then GoToAsync will throw an exception
• reworked all the INavigation methods to route through GoToAsync so that all behavior is symmetrical

Issues Resolved

• fixes [Bug] Shell.Current.GoToAsync("..", true) has no animation like Shell.Current.Navigation.PopAsync() #10638

API Changes

class ShellNavigatingDeferral
{
    public void Complete();
}

class ShellNavigatingEventArgs
{
     public ShellNavigatingDeferral GetDeferral()
}

Platforms Affected

• Core/XAML (all platforms)
• iOS
• Android
• UWP

Testing Procedure

• Unit tests included

Example usage

Given the following override of OnNavigating if the user tries to do any navigation they will be given a display sheet confirming if the want to navigate. If they click "no" then navigation will be cancelled

If the user calls GoToAsync the GoToAsync call will only resolve after the deferral token has been completed

public class MyShell : Shell
{
		protected override async void OnNavigating(ShellNavigatingEventArgs args)
		{
			base.OnNavigating(args);

			var token = args.GetDeferral();

			var result  = await DisplayActionSheet(
					"Are you sure?",
					"cancel",
					"destruction",
					"Yes", "No");

			if (result != "Yes")
				args.Cancel();

			token.Complete();
		}

DEMO

PR Checklist

• Targets the correct branch
• Tests are passing (or failures are unrelated)

[felipebaltazar]

🤎🤯🤎