From 2ec4be1b501dd11964dbb06d511e28188cc6b06f Mon Sep 17 00:00:00 2001
From: Shaun Lawrence <shaunrlawrence@gmail.com>
Date: Wed, 1 Nov 2023 22:44:22 +0000
Subject: [PATCH] PopupService (#1165)

* Added initial PopupService implementation

* Tweaks to allowing parameters to be passed to the view model behind a popup

* Tidy up xml docs

* Some unit tests

* Only create a view model instance if the BindingContext hasn't been set

* Remove the reliance on IQueryAttributable in favour of our own interface

* A better way to find the current Page

* Readonly dictionary and some safety checking around expected BindingContext types.

* A different attempt at passing parameters without an explicit interface

* Update src/CommunityToolkit.Maui/PopupService.cs

Co-authored-by: Pedro Jesus <pedrojesus.cefet@gmail.com>

* Now is a time for test

* Remove unnecessary changes

* Sample to perform a long running process

* Provide ability to close popup from within popup view model

* Prevent unnecessary instance being created

* Refactor `CurrentPage`, Add Default Constructor, Refactor `ValidateBindingContext`

* Update Unit Tests

---------

Co-authored-by: Pedro Jesus <pedrojesus.cefet@gmail.com>
Co-authored-by: Brandon Minnick <13558917+brminnick@users.noreply.github.com>
---
 .../MauiProgram.cs                            |   5 +-
 .../Pages/Views/Popup/MultiplePopupPage.xaml  |   6 +-
 .../Popup/CsharpBindingPopupViewModel.cs      |   7 +-
 .../Views/Popup/MultiplePopupViewModel.cs     |  27 +-
 .../Views/Popup/UpdatingPopupViewModel.cs     |  49 ++++
 .../Views/Popups/UpdatingPopup.xaml           |  55 ++++
 .../Views/Popups/UpdatingPopup.xaml.cs        |  20 ++
 .../IPopupService.cs                          |  54 ++++
 .../BaseHandlerTest.cs                        |  14 +-
 .../Mocks/MockPageViewModel.cs                |   1 +
 .../Mocks/MockPopupHandler.cs                 |   9 +-
 .../PopupServiceTests.cs                      | 276 ++++++++++++++++++
 .../AppBuilderExtensions.shared.cs            |   2 +
 .../ServiceCollectionExtensions.shared.cs     |  20 ++
 src/CommunityToolkit.Maui/PopupService.cs     | 149 ++++++++++
 15 files changed, 682 insertions(+), 12 deletions(-)
 create mode 100644 samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/UpdatingPopupViewModel.cs
 create mode 100644 samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml
 create mode 100644 samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml.cs
 create mode 100644 src/CommunityToolkit.Maui.Core/IPopupService.cs
 create mode 100644 src/CommunityToolkit.Maui.UnitTests/PopupServiceTests.cs
 create mode 100644 src/CommunityToolkit.Maui/PopupService.cs

diff --git a/samples/CommunityToolkit.Maui.Sample/MauiProgram.cs b/samples/CommunityToolkit.Maui.Sample/MauiProgram.cs
index 3cfe62c435..175a32efc7 100644
--- a/samples/CommunityToolkit.Maui.Sample/MauiProgram.cs
+++ b/samples/CommunityToolkit.Maui.Sample/MauiProgram.cs
@@ -195,8 +195,9 @@ static void RegisterViewsAndViewModels(in IServiceCollection services)
 		services.AddTransientWithShellRoute<StylePopupPage, StylePopupViewModel>();
 
 		// Add Popups
-		services.AddTransient<CsharpBindingPopup, CsharpBindingPopupViewModel>();
-		services.AddTransient<XamlBindingPopup, XamlBindingPopupViewModel>();
+		services.AddTransientPopup<CsharpBindingPopup, CsharpBindingPopupViewModel>();
+		services.AddTransientPopup<UpdatingPopup, UpdatingPopupViewModel>();
+		services.AddTransientPopup<XamlBindingPopup, XamlBindingPopupViewModel>();
 	}
 
 	static void RegisterEssentials(in IServiceCollection services)
diff --git a/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/MultiplePopupPage.xaml b/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/MultiplePopupPage.xaml
index 31013613d2..d05ab27ce4 100644
--- a/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/MultiplePopupPage.xaml
+++ b/samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/MultiplePopupPage.xaml
@@ -1,4 +1,4 @@
-<pages:BasePage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+<pages:BasePage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                 xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                 xmlns:pages="clr-namespace:CommunityToolkit.Maui.Sample.Pages"
                 xmlns:viewModels="clr-namespace:CommunityToolkit.Maui.Sample.ViewModels.Views"
@@ -28,7 +28,9 @@
 
                 <Button Text="XAML Binding Popup" Clicked="HandleXamlBindingPopupPopupButtonClicked" />
 
-                <Button Text="C# Binding Popup" Clicked="HandleCsharpBindingPopupButtonClicked" />
+                <Button Text="C# Binding Popup" Command="{Binding CsharpBindingPopupCommand}" />
+
+                <Button Text="Updating Popup" Command="{Binding UpdatingPopupCommand}" />
             </VerticalStackLayout>
         </ScrollView>
     </ContentPage.Content>
diff --git a/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/CsharpBindingPopupViewModel.cs b/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/CsharpBindingPopupViewModel.cs
index 02752494ae..9dabfc5bb2 100644
--- a/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/CsharpBindingPopupViewModel.cs
+++ b/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/CsharpBindingPopupViewModel.cs
@@ -4,5 +4,10 @@ public sealed partial class CsharpBindingPopupViewModel : BaseViewModel
 {
 	public string Title { get; } = "C# Binding Popup";
 
-	public string Message { get; } = "This is a platform specific popup with a .NET MAUI View being rendered. The behaviors of the popup will confirm to 100% this platform look and feel, but still allows you to use your .NET MAUI Controls.";
+	public string Message { get; private set; } = "";
+
+	internal void Load(string message)
+	{
+		Message = message;
+	}
 }
\ No newline at end of file
diff --git a/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs b/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs
index 6d51f8336c..5f08474732 100644
--- a/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs
+++ b/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs
@@ -1,5 +1,28 @@
-namespace CommunityToolkit.Maui.Sample.ViewModels.Views;
+using CommunityToolkit.Maui.Core;
+using CommunityToolkit.Mvvm.Input;
 
-public class MultiplePopupViewModel : BaseViewModel
+namespace CommunityToolkit.Maui.Sample.ViewModels.Views;
+
+public partial class MultiplePopupViewModel : BaseViewModel
 {
+	readonly IPopupService popupService;
+
+	public MultiplePopupViewModel(IPopupService popupService)
+	{
+		this.popupService = popupService;
+	}
+
+	[RelayCommand]
+	Task OnCsharpBindingPopup()
+	{
+		return popupService.ShowPopupAsync<CsharpBindingPopupViewModel>(
+			onPresenting: viewModel => viewModel.Load("This is a platform specific popup with a .NET MAUI View being rendered. The behaviors of the popup will confirm to 100% this platform look and feel, but still allows you to use your .NET MAUI Controls."));
+	}
+
+	[RelayCommand]
+	Task OnUpdatingPopup()
+	{
+		return popupService.ShowPopupAsync<UpdatingPopupViewModel>(
+			onPresenting: viewModel => viewModel.PerformUpdates(10));
+	}
 }
\ No newline at end of file
diff --git a/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/UpdatingPopupViewModel.cs b/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/UpdatingPopupViewModel.cs
new file mode 100644
index 0000000000..e75f84ef90
--- /dev/null
+++ b/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/UpdatingPopupViewModel.cs
@@ -0,0 +1,49 @@
+using CommunityToolkit.Mvvm.ComponentModel;
+using CommunityToolkit.Mvvm.Input;
+
+namespace CommunityToolkit.Maui.Sample.ViewModels.Views;
+
+public partial class UpdatingPopupViewModel : BaseViewModel
+{
+	const double finalUpdateProgressValue = 1;
+	
+	readonly WeakEventManager finishedEventManager = new();
+	
+	[ObservableProperty]
+	string message = "";
+
+	[ObservableProperty]
+	[NotifyCanExecuteChangedFor(nameof(FinishCommand))]
+	double updateProgress;
+
+	public event EventHandler<EventArgs> Finished
+	{
+		add => finishedEventManager.AddEventHandler(value);
+		remove => finishedEventManager.RemoveEventHandler(value);
+	}
+
+	internal async void PerformUpdates(int numberOfUpdates)
+	{
+		double updateTotalForPercentage = numberOfUpdates + 1;
+
+		for (var update = 1; update <= numberOfUpdates; update++)
+		{
+			Message = $"Updating {update} of {numberOfUpdates}";
+
+			UpdateProgress = update / updateTotalForPercentage;
+
+			await Task.Delay(TimeSpan.FromSeconds(1));	
+		}
+
+		UpdateProgress = finalUpdateProgressValue;
+		Message = "Updates complete";
+	}
+
+	[RelayCommand(CanExecute = nameof(CanFinish))]
+	void OnFinish()
+	{
+		finishedEventManager.HandleEvent(this, EventArgs.Empty, nameof(Finished));
+	}
+
+	bool CanFinish() => UpdateProgress is finalUpdateProgressValue;
+}
diff --git a/samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml b/samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml
new file mode 100644
index 0000000000..95c00985d8
--- /dev/null
+++ b/samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<toolkit:Popup
+	x:Class="CommunityToolkit.Maui.Sample.Views.Popups.UpdatingPopup"
+	xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
+	xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+	xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
+	CanBeDismissedByTappingOutsideOfPopup="False">
+
+	<VerticalStackLayout Style="{StaticResource PopupLayout}" Spacing="12" >
+		<VerticalStackLayout.Resources>
+			<ResourceDictionary>
+				<Style x:Key="Title" TargetType="Label">
+					<Setter Property="FontSize" Value="26" />
+					<Setter Property="FontAttributes" Value="Bold" />
+					<Setter Property="TextColor" Value="#000" />
+					<Setter Property="VerticalTextAlignment" Value="Center" />
+					<Setter Property="HorizontalTextAlignment" Value="Center" />
+				</Style>
+				<Style x:Key="Divider" TargetType="BoxView">
+					<Setter Property="HeightRequest" Value="1" />
+					<Setter Property="Margin" Value="50, 25" />
+					<Setter Property="Color" Value="#c3c3c3" />
+				</Style>
+				<Style x:Key="Content" TargetType="Label">
+					<Setter Property="HorizontalTextAlignment" Value="Center" />
+					<Setter Property="VerticalTextAlignment" Value="Center" />
+				</Style>
+				<Style x:Key="PopupLayout" TargetType="StackLayout">
+					<Setter Property="Padding" Value="{OnPlatform Android=20, WinUI=20, iOS=12, MacCatalyst=5, Tizen=20}" />
+				</Style>
+				<Style x:Key="ConfirmButton" TargetType="Button">
+					<Setter Property="VerticalOptions" Value="EndAndExpand" />
+				</Style>
+
+				<x:Double x:Key="ComparingValue">1.0</x:Double>
+			</ResourceDictionary>
+		</VerticalStackLayout.Resources>
+
+		<Label Style="{StaticResource Title}" Text="Updating" />
+
+		<BoxView Style="{StaticResource Divider}" />
+
+		<ActivityIndicator
+			IsRunning="{Binding UpdateProgress, Converter={toolkit:CompareConverter ComparingValue={StaticResource ComparingValue}, ComparisonOperator=Smaller, FalseObject=False, TrueObject=True}}"/>
+
+		<Label Style="{StaticResource Content}" Text="{Binding Message}" />
+
+		<ProgressBar Progress="{Binding UpdateProgress}" />
+
+		<Button
+			Command="{Binding FinishCommand}"
+			Style="{StaticResource ConfirmButton}"
+			Text="Finish" />
+	</VerticalStackLayout>
+</toolkit:Popup>
\ No newline at end of file
diff --git a/samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml.cs b/samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml.cs
new file mode 100644
index 0000000000..1f49054be7
--- /dev/null
+++ b/samples/CommunityToolkit.Maui.Sample/Views/Popups/UpdatingPopup.xaml.cs
@@ -0,0 +1,20 @@
+using CommunityToolkit.Maui.Sample.ViewModels.Views;
+using CommunityToolkit.Maui.Views;
+
+namespace CommunityToolkit.Maui.Sample.Views.Popups;
+
+public partial class UpdatingPopup : Popup
+{
+	public UpdatingPopup(UpdatingPopupViewModel updatingPopupViewModel)
+	{
+		InitializeComponent();
+		BindingContext = updatingPopupViewModel;
+
+		updatingPopupViewModel.Finished += OnUpdatingPopupViewModelFinished;
+	}
+
+	void OnUpdatingPopupViewModelFinished(object? sender, EventArgs e)
+	{
+		this.Close();
+	}
+}
diff --git a/src/CommunityToolkit.Maui.Core/IPopupService.cs b/src/CommunityToolkit.Maui.Core/IPopupService.cs
new file mode 100644
index 0000000000..304902be13
--- /dev/null
+++ b/src/CommunityToolkit.Maui.Core/IPopupService.cs
@@ -0,0 +1,54 @@
+using System.ComponentModel;
+
+namespace CommunityToolkit.Maui.Core;
+
+/// <summary>
+/// Provides a mechanism for displaying <see cref="CommunityToolkit.Maui.Core.IPopup"/>s based on the underlying view model.
+/// </summary>
+public interface IPopupService
+{
+	/// <summary>
+	/// Resolves and displays a <see cref="CommunityToolkit.Maui.Core.IPopup"/> and <typeparamref name="TViewModel"/> pair that was registered with <c>AddTransientPopup</c>.
+	/// </summary>
+	/// <typeparam name="TViewModel">The type of the view model registered with the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</typeparam>
+	void ShowPopup<TViewModel>() where TViewModel : INotifyPropertyChanged;
+
+	/// <summary>
+	/// Resolves and displays a <see cref="CommunityToolkit.Maui.Core.IPopup"/> and <typeparamref name="TViewModel"/> pair that was registered with <c>AddTransientPopup</c>.
+	/// The supplied <paramref name="onPresenting"/> provides a mechanism to invoke any methods on your view model in order to load or pass data to it.
+	/// </summary>
+	/// <typeparam name="TViewModel">The type of the view model registered with the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</typeparam>
+	/// <param name="onPresenting">An <see cref="Action{TViewModel}"/> that will be performed before the popup is presented.</param>
+	void ShowPopup<TViewModel>(Action<TViewModel> onPresenting) where TViewModel : INotifyPropertyChanged;
+
+	/// <summary>
+	/// Resolves and displays a <see cref="CommunityToolkit.Maui.Core.IPopup"/> and <typeparamref name="TViewModel"/> pair that was registered with <c>AddTransientPopup</c>.
+	/// </summary>
+	/// <typeparam name="TViewModel">The type of the view model registered with the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</typeparam>
+	/// <param name="viewModel">The view model to use as the <c>BindingContext</c> for the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</param>
+	void ShowPopup<TViewModel>(TViewModel viewModel) where TViewModel : INotifyPropertyChanged;
+
+	/// <summary>
+	/// Resolves and displays a <see cref="CommunityToolkit.Maui.Core.IPopup"/> and <typeparamref name="TViewModel"/> pair that was registered with <c>AddTransientPopup</c>.
+	/// </summary>
+	/// <typeparam name="TViewModel">The type of the view model registered with the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</typeparam>
+	/// <returns>A <see cref="Task"/> that can be awaited to return the result of the <see cref="CommunityToolkit.Maui.Core.IPopup"/> once it has been dismissed.</returns>
+	Task<object?> ShowPopupAsync<TViewModel>() where TViewModel : INotifyPropertyChanged;
+
+	/// <summary>
+	/// Resolves and displays a <see cref="CommunityToolkit.Maui.Core.IPopup"/> and <typeparamref name="TViewModel"/> pair that was registered with <c>AddTransientPopup</c>.
+	/// The supplied <paramref name="onPresenting"/> provides a mechanism to invoke any methods on your view model in order to load or pass data to it.
+	/// </summary>
+	/// <typeparam name="TViewModel">The type of the view model registered with the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</typeparam>
+	/// <returns>A <see cref="Task"/> that can be awaited to return the result of the <see cref="CommunityToolkit.Maui.Core.IPopup"/> once it has been dismissed.</returns>
+	/// <param name="onPresenting">An <see cref="Action{TViewModel}"/> that will be performed before the popup is presented.</param>
+	Task<object?> ShowPopupAsync<TViewModel>(Action<TViewModel> onPresenting) where TViewModel : INotifyPropertyChanged;
+
+	/// <summary>
+	/// Resolves and displays a <see cref="CommunityToolkit.Maui.Core.IPopup"/> and <typeparamref name="TViewModel"/> pair that was registered with <c>AddTransientPopup</c>.
+	/// </summary>
+	/// <typeparam name="TViewModel">The type of the view model registered with the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</typeparam>
+	/// <param name="viewModel">The view model to use as the <c>BindingContext</c> for the <see cref="CommunityToolkit.Maui.Core.IPopup"/>.</param>
+	/// <returns>A <see cref="Task"/> that can be awaited to return the result of the <see cref="CommunityToolkit.Maui.Core.IPopup"/> once it has been dismissed.</returns>
+	Task<object?> ShowPopupAsync<TViewModel>(TViewModel viewModel) where TViewModel : INotifyPropertyChanged;
+}
diff --git a/src/CommunityToolkit.Maui.UnitTests/BaseHandlerTest.cs b/src/CommunityToolkit.Maui.UnitTests/BaseHandlerTest.cs
index d997543776..4dbf242893 100644
--- a/src/CommunityToolkit.Maui.UnitTests/BaseHandlerTest.cs
+++ b/src/CommunityToolkit.Maui.UnitTests/BaseHandlerTest.cs
@@ -6,8 +6,11 @@ public abstract class BaseHandlerTest : BaseTest
 {
 	protected BaseHandlerTest()
 	{
-		CreateAndSetMockApplication();
+		CreateAndSetMockApplication(out var serviceProvider);
+		ServiceProvider = serviceProvider;
 	}
+	
+	protected IServiceProvider ServiceProvider { get; } 
 
 	protected static TElementHandler CreateElementHandler<TElementHandler>(Microsoft.Maui.IElement view, bool hasMauiContext = true)
 		where TElementHandler : IElementHandler, new()
@@ -17,7 +20,7 @@ protected static TElementHandler CreateElementHandler<TElementHandler>(Microsoft
 
 		if (hasMauiContext)
 		{
-			mockElementHandler.SetMauiContext(Application.Current?.Handler.MauiContext ?? throw new NullReferenceException());
+			mockElementHandler.SetMauiContext(Application.Current?.Handler?.MauiContext ?? throw new NullReferenceException());
 		}
 
 		return mockElementHandler;
@@ -31,20 +34,23 @@ protected static TViewHandler CreateViewHandler<TViewHandler>(IView view, bool h
 
 		if (hasMauiContext)
 		{
-			mockViewHandler.SetMauiContext(Application.Current?.Handler.MauiContext ?? throw new NullReferenceException());
+			mockViewHandler.SetMauiContext(Application.Current?.Handler?.MauiContext ?? throw new NullReferenceException());
 		}
 
 		return mockViewHandler;
 	}
 
-	static void CreateAndSetMockApplication()
+	static void CreateAndSetMockApplication(out IServiceProvider serviceProvider)
 	{
 		var appBuilder = MauiApp.CreateBuilder()
 								.UseMauiCommunityToolkit()
 								.UseMauiApp<MockApplication>();
 
 		var mauiApp = appBuilder.Build();
+
 		var application = mauiApp.Services.GetRequiredService<IApplication>();
+		serviceProvider = mauiApp.Services;
+		
 		application.Handler = new ApplicationHandlerStub();
 		application.Handler.SetMauiContext(new HandlersContextStub(mauiApp.Services));
 	}
diff --git a/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPageViewModel.cs b/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPageViewModel.cs
index 961e1c09f6..227359d82d 100644
--- a/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPageViewModel.cs
+++ b/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPageViewModel.cs
@@ -2,4 +2,5 @@
 
 public class MockPageViewModel : BindableObject
 {
+	public bool HasLoaded { get; set; }
 }
\ No newline at end of file
diff --git a/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPopupHandler.cs b/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPopupHandler.cs
index e4f265d08c..407065186c 100644
--- a/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPopupHandler.cs
+++ b/src/CommunityToolkit.Maui.UnitTests/Mocks/MockPopupHandler.cs
@@ -7,7 +7,8 @@ public class MockPopupHandler : ElementHandler<IPopup, object>
 {
 	public static CommandMapper<IPopup, MockPopupHandler> PopUpCommandMapper = new(ElementCommandMapper)
 	{
-		[nameof(IPopup.OnOpened)] = MapOnOpened
+		[nameof(IPopup.OnOpened)] = MapOnOpened,
+		[nameof(IPopup.OnClosed)] = MapOnClosed,
 	};
 
 	public MockPopupHandler() : base(new PropertyMapper<IView>(), PopUpCommandMapper)
@@ -30,5 +31,11 @@ protected override object CreatePlatformElement()
 	static void MapOnOpened(MockPopupHandler arg1, IPopup arg2, object? arg3)
 	{
 		arg1.OnOpenedCount++;
+		arg2.OnOpened();
+	}
+
+	static void MapOnClosed(MockPopupHandler handler, IPopup view, object? result)
+	{
+		view.HandlerCompleteTCS.TrySetResult();
 	}
 }
\ No newline at end of file
diff --git a/src/CommunityToolkit.Maui.UnitTests/PopupServiceTests.cs b/src/CommunityToolkit.Maui.UnitTests/PopupServiceTests.cs
new file mode 100644
index 0000000000..a3afd3c746
--- /dev/null
+++ b/src/CommunityToolkit.Maui.UnitTests/PopupServiceTests.cs
@@ -0,0 +1,276 @@
+using System.ComponentModel;
+using CommunityToolkit.Maui.Core;
+using CommunityToolkit.Maui.UnitTests.Mocks;
+using CommunityToolkit.Maui.Views;
+using Xunit;
+
+namespace CommunityToolkit.Maui.UnitTests;
+
+public class PopupServiceTests : BaseHandlerTest
+{
+	public PopupServiceTests()
+	{
+		var appBuilder = MauiApp.CreateBuilder()
+			.UseMauiCommunityToolkit()
+			.UseMauiApp<MockApplication>();
+
+		var mauiApp = appBuilder.Build();
+		var application = mauiApp.Services.GetRequiredService<IApplication>();
+		application.Handler = new ApplicationHandlerStub();
+		application.Handler.SetMauiContext(new HandlersContextStub(mauiApp.Services));
+	}
+
+	static PopupServiceTests()
+	{
+		var serviceCollection = new ServiceCollection();
+		PopupService.AddTransientPopup<MockPopup, MockPageViewModel>(serviceCollection);
+	}
+
+	[Fact]
+	public void ShowPopupAsyncWithNullViewModelShouldThrowArgumentNullException()
+	{
+		var popupService = new PopupService(new MockServiceProvider());
+
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		Assert.ThrowsAsync<ArgumentNullException>(() =>
+			popupService.ShowPopupAsync<INotifyPropertyChanged>(viewModel: null));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact]
+	public void ShowPopupAsyncWithNullOnPresentingShouldThrowArgumentNullException()
+	{
+		var popupService = new PopupService(new MockServiceProvider());
+
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		Assert.ThrowsAsync<ArgumentNullException>(() =>
+			popupService.ShowPopupAsync<INotifyPropertyChanged>(onPresenting: null));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact]
+	public void ShowPopupAsyncWithMismatchedViewModelTypeShouldThrowInvalidOperationException()
+	{
+		var popupService = new PopupService(new MockServiceProvider());
+
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		Assert.ThrowsAsync<ArgumentNullException>(() =>
+			popupService.ShowPopupAsync<INotifyPropertyChanged>(viewModel: null));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact(Timeout = 2000)]
+	public void ShowPopupAsyncShouldThrowInvalidOperationExceptionWhenNoViewModelIsRegistered()
+	{
+		var popupInstance = new MockMismatchedPopup();
+		var popupViewModel = new MockPageViewModel();
+
+		SetupTest(popupInstance, () => popupViewModel, out var popupService);
+
+		Assert.ThrowsAsync<InvalidOperationException>(popupService.ShowPopupAsync<MockPageViewModel>);
+	}
+
+	[Fact(Timeout = 2000)]
+	public async Task ShowPopupAsyncShouldValidateProperBindingContext()
+	{
+		var popupViewModel = new MockPageViewModel();
+		var popupInstance = new MockSelfClosingPopup(string.Empty)
+		{
+			BindingContext = popupViewModel
+		};
+
+		SetupTest(popupInstance, () => popupViewModel, out var popupService);
+
+		await popupService.ShowPopupAsync<MockPageViewModel>();
+
+		Assert.Same(popupInstance.BindingContext, popupViewModel);
+	}
+
+	[Fact(Timeout = 2000)]
+	public async Task ShowPopupAsyncWithOnPresentingShouldBeInvoked()
+	{
+		var popupViewModel = new MockPageViewModel();
+		var popupInstance = new MockSelfClosingPopup(string.Empty)
+		{
+			BindingContext = popupViewModel
+		};
+
+		SetupTest(popupInstance, () => popupViewModel, out var popupService);
+
+		await popupService.ShowPopupAsync<MockPageViewModel>(onPresenting: viewModel => viewModel.HasLoaded = true);
+
+		Assert.True(popupViewModel.HasLoaded);
+	}
+
+	[Fact(Timeout = 2000)]
+	public async Task ShowPopupAsyncShouldReturnResultOnceClosed()
+	{
+		var expectedResult = new object();
+
+		var popupViewModel = new MockPageViewModel();
+		var popupInstance = new MockSelfClosingPopup(expectedResult)
+		{
+			BindingContext = popupViewModel
+		};
+
+		SetupTest(popupInstance, () => popupViewModel, out var popupService);
+
+		var result = await popupService.ShowPopupAsync<MockPageViewModel>();
+
+		Assert.Same(expectedResult, result);
+	}
+
+	[Fact]
+	public void ShowPopupWithNullViewModelShouldThrowArgumentNullException()
+	{
+		var popupService = new PopupService(new MockServiceProvider());
+
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		Assert.Throws<ArgumentNullException>(() => popupService.ShowPopup<INotifyPropertyChanged>(viewModel: null));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact]
+	public void ShowPopupWithNullOnPresentingShouldThrowArgumentNullException()
+	{
+		var popupService = new PopupService(new MockServiceProvider());
+
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		Assert.Throws<ArgumentNullException>(() => popupService.ShowPopup<INotifyPropertyChanged>(onPresenting: null));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact]
+	public void ShowPopupWithMismatchedViewModelTypeShouldThrowInvalidOperationException()
+	{
+		var popupService = new PopupService(new MockServiceProvider());
+
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		Assert.Throws<ArgumentNullException>(() => popupService.ShowPopup<INotifyPropertyChanged>(viewModel: null));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact]
+	public void ShowPopupShouldThrowInvalidOperationExceptionWhenNoViewModelIsRegistered()
+	{
+		var popupInstance = new MockMismatchedPopup();
+		var popupViewModel = new MockPageViewModel();
+
+		SetupTest(popupInstance, () => popupViewModel, out var popupService);
+
+		Assert.Throws<InvalidOperationException>(popupService.ShowPopup<MockPageViewModel>);
+	}
+
+	[Fact]
+	public void ShowPopupWithOnPresentingShouldBeInvoked()
+	{
+		var popupViewModel = new MockPageViewModel();
+		var popupInstance = new MockPopup
+		{
+			BindingContext = popupViewModel
+		};
+
+		SetupTest(popupInstance, () => popupViewModel, out var popupService);
+
+		popupService.ShowPopup<MockPageViewModel>(onPresenting: viewModel => viewModel.HasLoaded = true);
+
+		Assert.True(popupViewModel.HasLoaded);
+	}
+
+	static void SetupTest(
+		Popup popup,
+		Func<INotifyPropertyChanged> createViewModelInstance,
+		out IPopupService popupService)
+	{
+		popupService = new PopupService(
+			MockServiceProvider.ThatProvides(
+				(implementation: popup, forType: typeof(MockPopup)),
+				(implementation: createViewModelInstance.Invoke(), forType: typeof(MockPageViewModel))));
+
+		var app = Application.Current ?? throw new NullReferenceException();
+
+		var page = new ContentPage
+		{
+			Content = new Label
+			{
+				Text = "Hello there"
+			}
+		};
+
+		// Make sure that our page will have a Handler
+		CreateViewHandler<MockPageHandler>(page);
+
+		app.MainPage = page;
+
+		CreateElementHandler<MockPopupHandler>(popup);
+
+		Assert.NotNull(popup.Handler);
+		Assert.NotNull(page.Handler);
+	}
+
+	class MockServiceProvider : IServiceProvider
+	{
+		readonly IDictionary<Type, object> registrations = new Dictionary<Type, object>();
+
+		public MockServiceProvider()
+		{
+		}
+
+		MockServiceProvider(params (object implementation, Type forType)[] registrations) : this()
+		{
+			foreach (var (implementation, forType) in registrations)
+			{
+				this.registrations.Add(forType, implementation);
+			}
+		}
+
+		public static MockServiceProvider ThatProvides(params (object implementation, Type forType)[] registrations)
+		{
+			return new MockServiceProvider(registrations);
+		}
+
+		public object? GetService(Type serviceType)
+		{
+			if (registrations.TryGetValue(serviceType, out var registeredImplementation))
+			{
+				return registeredImplementation;
+			}
+
+			return null;
+		}
+	}
+
+	class MockPopup : Popup
+	{
+		public MockPopup()
+		{
+		}
+	}
+
+	class MockSelfClosingPopup : Popup
+	{
+		readonly object result;
+
+		public MockSelfClosingPopup(object result)
+		{
+			this.result = result;
+		}
+
+		internal override async void OnOpened()
+		{
+			base.OnOpened();
+
+			await Task.Delay(TimeSpan.FromSeconds(1));
+
+			Close(result);
+		}
+	}
+
+	class MockMismatchedPopup : Popup
+	{
+		public MockMismatchedPopup()
+		{
+			BindingContext = new object();
+		}
+	}
+}
\ No newline at end of file
diff --git a/src/CommunityToolkit.Maui/AppBuilderExtensions.shared.cs b/src/CommunityToolkit.Maui/AppBuilderExtensions.shared.cs
index 9d151eb7d7..100bce9c29 100644
--- a/src/CommunityToolkit.Maui/AppBuilderExtensions.shared.cs
+++ b/src/CommunityToolkit.Maui/AppBuilderExtensions.shared.cs
@@ -20,6 +20,8 @@ public static MauiAppBuilder UseMauiCommunityToolkit(this MauiAppBuilder builder
 		// Pass `null` because `options?.Invoke()` will set options on both `CommunityToolkit.Maui` and `CommunityToolkit.Maui.Core`
 		builder.UseMauiCommunityToolkitCore(null);
 
+		builder.Services.AddSingleton<IPopupService, PopupService>();
+
 		// Invokes options for both `CommunityToolkit.Maui` and `CommunityToolkit.Maui.Core`
 		options?.Invoke(new Options());
 
diff --git a/src/CommunityToolkit.Maui/Extensions/ServiceCollectionExtensions.shared.cs b/src/CommunityToolkit.Maui/Extensions/ServiceCollectionExtensions.shared.cs
index 5629a747e2..76e82d1dee 100644
--- a/src/CommunityToolkit.Maui/Extensions/ServiceCollectionExtensions.shared.cs
+++ b/src/CommunityToolkit.Maui/Extensions/ServiceCollectionExtensions.shared.cs
@@ -1,4 +1,5 @@
 using System.ComponentModel;
+using CommunityToolkit.Maui.Views;
 
 // Using root CommunityToolkit.Maui namespace so these extension methods
 // light up in MauiProgram when CommunityToolkit.Maui namespace is imported 
@@ -32,6 +33,25 @@ public static IServiceCollection AddTransient<TView, TViewModel>(this IServiceCo
 			.AddTransient<TView>();
 	}
 
+	/// <summary>
+	/// Adds a <see cref="Popup"/> of the type specified in <typeparamref name="TPopupView"/> and a ViewModel
+	/// of the type specified in <typeparamref name="TPopupViewModel"/> to the specified
+	/// <see cref="IServiceCollection"/> with <see cref="ServiceLifetime.Transient"/> lifetime.
+	/// </summary>
+	/// <typeparam name="TPopupView">The type of the Popup to add. Constrained to <see cref="Popup"/></typeparam>
+	/// <typeparam name="TPopupViewModel">The type of the ViewModel to add. Constrained to 
+	/// <see cref="INotifyPropertyChanged"/></typeparam>
+	/// <param name="services">The <see cref="IServiceCollection"/> to add the service to.</param>
+	/// <returns>A reference to this instance after the operation has completed.</returns>
+	public static IServiceCollection AddTransientPopup<TPopupView, TPopupViewModel>(this IServiceCollection services)
+		where TPopupView : Popup
+		where TPopupViewModel : INotifyPropertyChanged
+	{
+		PopupService.AddTransientPopup<TPopupView, TPopupViewModel>(services);
+
+		return services;
+	}
+
 	/// <summary>
 	/// Adds a <see cref="NavigableElement"/> of the type specified in <typeparamref name="TView"/> and a ViewModel
 	/// of the type specified in <typeparamref name="TViewModel"/> to the specified
diff --git a/src/CommunityToolkit.Maui/PopupService.cs b/src/CommunityToolkit.Maui/PopupService.cs
new file mode 100644
index 0000000000..61ab714809
--- /dev/null
+++ b/src/CommunityToolkit.Maui/PopupService.cs
@@ -0,0 +1,149 @@
+using System.ComponentModel;
+using CommunityToolkit.Maui.Core;
+using CommunityToolkit.Maui.Views;
+using Microsoft.Maui.Controls.Platform;
+
+namespace CommunityToolkit.Maui;
+
+/// <inheritdoc cref="IPopupService"/>
+public class PopupService : IPopupService
+{
+	readonly IServiceProvider serviceProvider;
+
+	static readonly Dictionary<Type, Type> viewModelToViewMappings = new();
+
+	static Page CurrentPage =>
+		PageExtensions.GetCurrentPage(
+			Application.Current?.MainPage ?? throw new InvalidOperationException("Application.Current.MainPage cannot be null."));
+
+	/// <summary>
+	/// Creates a new instance of <see cref="PopupService"/>.
+	/// </summary>
+	/// <param name="serviceProvider">The <see cref="IServiceProvider"/> implementation.</param>
+	[ActivatorUtilitiesConstructor]
+	public PopupService(IServiceProvider serviceProvider)
+	{
+		this.serviceProvider = serviceProvider;
+	}
+	
+	/// <summary>
+	/// Creates a new instance of <see cref="PopupService"/>.
+	/// </summary>
+	public PopupService()
+	{
+		serviceProvider = Application.Current?.Handler?.MauiContext?.Services 
+							?? throw new InvalidOperationException("Could not locate IServiceProvider");
+	}
+
+	internal static void AddTransientPopup<TPopupView, TPopupViewModel>(IServiceCollection services)
+		where TPopupView : IPopup
+		where TPopupViewModel : INotifyPropertyChanged
+	{
+		viewModelToViewMappings.Add(typeof(TPopupViewModel), typeof(TPopupView));
+
+		services.AddTransient(typeof(TPopupView));
+		services.AddTransient(typeof(TPopupViewModel));
+	}
+
+	/// <inheritdoc cref="IPopupService.ShowPopup{TViewModel}()"/>
+	public void ShowPopup<TViewModel>() where TViewModel : INotifyPropertyChanged
+	{
+		var popup = GetPopup(typeof(TViewModel));
+
+		ValidateBindingContext<TViewModel>(popup, out _);
+
+		CurrentPage.ShowPopup(popup);
+	}
+
+	/// <inheritdoc cref="IPopupService.ShowPopup{TViewModel}(TViewModel)"/>
+	public void ShowPopup<TViewModel>(TViewModel viewModel) where TViewModel : INotifyPropertyChanged
+	{
+		ArgumentNullException.ThrowIfNull(viewModel);
+
+		var popup = GetPopup(typeof(TViewModel));
+
+		ValidateBindingContext<TViewModel>(popup, out _);
+
+		CurrentPage.ShowPopup(popup);
+	}
+
+	/// <inheritdoc cref="IPopupService.ShowPopup{TViewModel}(Action{TViewModel})"/>
+	public void ShowPopup<TViewModel>(Action<TViewModel> onPresenting) where TViewModel : INotifyPropertyChanged
+	{
+		ArgumentNullException.ThrowIfNull(onPresenting);
+
+		var popup = GetPopup(typeof(TViewModel));
+
+		ValidateBindingContext(popup, out TViewModel viewModel);
+
+		onPresenting.Invoke(viewModel);
+
+		CurrentPage.ShowPopup(popup);
+	}
+
+	/// <inheritdoc cref="IPopupService.ShowPopupAsync{TViewModel}()"/>
+	public Task<object?> ShowPopupAsync<TViewModel>() where TViewModel : INotifyPropertyChanged
+	{
+		var popup = GetPopup(typeof(TViewModel));
+
+		ValidateBindingContext<TViewModel>(popup, out _);
+
+		return CurrentPage.ShowPopupAsync(popup);
+	}
+
+	/// <inheritdoc cref="IPopupService.ShowPopupAsync{TViewModel}(TViewModel)"/>
+	public Task<object?> ShowPopupAsync<TViewModel>(TViewModel viewModel) where TViewModel : INotifyPropertyChanged
+	{
+		ArgumentNullException.ThrowIfNull(viewModel);
+
+		var popup = GetPopup(typeof(TViewModel));
+
+		ValidateBindingContext<TViewModel>(popup, out _);
+
+		return CurrentPage.ShowPopupAsync(popup);
+	}
+
+	/// <inheritdoc cref="IPopupService.ShowPopupAsync{TViewModel}(Action{TViewModel})"/>
+	public Task<object?> ShowPopupAsync<TViewModel>(Action<TViewModel> onPresenting) where TViewModel : INotifyPropertyChanged
+	{
+		ArgumentNullException.ThrowIfNull(onPresenting);
+
+		var popup = GetPopup(typeof(TViewModel));
+
+		ValidateBindingContext(popup, out TViewModel viewModel);
+
+		onPresenting.Invoke(viewModel);
+
+		return CurrentPage.ShowPopupAsync(popup);
+	}
+
+	/// <summary>
+	/// Ensures that the BindingContext property of the Popup to present is properly assigned and of the expected type.
+	/// </summary>
+	/// <typeparam name="TViewModel"></typeparam>
+	/// <param name="popup">The popup to be presented.</param>
+	/// <param name="bindingContext">Validated View Model</param>
+	/// <exception cref="InvalidOperationException"></exception>
+	static void ValidateBindingContext<TViewModel>(Popup popup, out TViewModel bindingContext)
+	{
+		if (popup.BindingContext is not TViewModel viewModel)
+		{
+			throw new InvalidOperationException($"Unexpected type has been assigned to the BindingContext of {popup.GetType().FullName}. Expected type {typeof(TViewModel).FullName} but was {popup.BindingContext?.GetType().FullName?? "null"}");
+		}
+
+		bindingContext = viewModel;
+	}
+
+	Popup GetPopup(Type viewModelType)
+	{
+		var popup = serviceProvider.GetService(viewModelToViewMappings[viewModelType]) as Popup;
+		
+		if (popup is null)
+		{
+			throw new InvalidOperationException(
+				$"Unable to resolve popup type for {viewModelType} please make sure that you have called {nameof(AddTransientPopup)}");
+		}
+
+		return popup;
+	}
+}