Return IPopupResult from PopupExtensions.ClosePopupAsync() (#2677)

* Return `IPopupResult`

* `dotnet format`

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add `GetMostRecentPopupPage()`

* Update XML

* Update src/CommunityToolkit.Maui.UnitTests/Extensions/PopupExtensionsTests.cs

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add Unit Tests

* Update XML

---------

Co-authored-by: Brandon Minnick <13558917+brminnick@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: TheCodeTraveler

src/CommunityToolkit.Maui.UnitTests/Extensions/PopupExtensionsTests.cs

@@ -36,38 +36,90 @@ public async Task ClosePopup_TokenExpired_ShouldThrowOperationCancelledException
 	{
 		// Arrange
 		var cts = new CancellationTokenSource();
-		
+
 		// Act
 		await cts.CancelAsync();
-		
+
 		// Assert
 		await Assert.ThrowsAsync<OperationCanceledException>(() => navigation.ClosePopupAsync(cts.Token));
 	}
-	
+
 	[Fact(Timeout = (int)TestDuration.Short)]
 	public async Task ClosePopup_NoExistingPopup_ShouldThrowPopupNotFoundException()
 	{
 		// Arrange
-		
+
 		// Act
-		
+
 		// Assert
 		await Assert.ThrowsAsync<PopupNotFoundException>(() => navigation.ClosePopupAsync(TestContext.Current.CancellationToken));
 	}
-	
+
 	[Fact(Timeout = (int)TestDuration.Short)]
 	public async Task ClosePopup_PopupBlocked_ShouldThrowPopupBlockedException()
 	{
 		// Arrange
-		
+
 		// Act
 		navigation.ShowPopup(new Button());
 		await navigation.PushModalAsync(new ContentPage());
-		
+
 		// Assert
 		await Assert.ThrowsAsync<PopupBlockedException>(() => navigation.ClosePopupAsync(TestContext.Current.CancellationToken));
 	}
 
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopup_NullPage_ShouldThrowArgumentNullException()
+	{
+		// Arrange
+
+		// Act
+
+		// Assert
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		await Assert.ThrowsAsync<ArgumentNullException>(() => PopupExtensions.ClosePopupAsync((Page?)null, TestContext.Current.CancellationToken));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopup_NullNavigation_ShouldThrowArgumentNullException()
+	{
+		// Arrange
+
+		// Act
+
+		// Assert
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		await Assert.ThrowsAsync<ArgumentNullException>(() => PopupExtensions.ClosePopupAsync((INavigation?)null, TestContext.Current.CancellationToken));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopupT_NullPage_ShouldThrowArgumentNullException()
+	{
+		// Arrange
+
+		// Act
+
+		// Assert
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		await Assert.ThrowsAsync<ArgumentNullException>(() => PopupExtensions.ClosePopupAsync((Page?)null, 2, TestContext.Current.CancellationToken));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopupT_NullNavigation_ShouldThrowArgumentNullException()
+	{
+		// Arrange
+
+		// Act
+
+		// Assert
+#pragma warning disable CS8625 // Cannot convert null literal to non-nullable reference type.
+		await Assert.ThrowsAsync<ArgumentNullException>(() => PopupExtensions.ClosePopupAsync((INavigation?)null, 2, TestContext.Current.CancellationToken));
+#pragma warning restore CS8625 // Cannot convert null literal to non-nullable reference type.
+	}
+
 	[Fact(Timeout = (int)TestDuration.Short)]
 	public async Task ShowPopupAsync_WithPopupType_ShowsPopupAndClosesPopup()
 	{
@@ -80,10 +132,10 @@ public async Task ShowPopupAsync_WithPopupType_ShowsPopupAndClosesPopup()
 		// Assert
 		Assert.Single(navigation.ModalStack);
 		Assert.IsType<PopupPage>(navigation.ModalStack[0]);
-		
+
 		// Act
 		await navigation.ClosePopupAsync(TestContext.Current.CancellationToken);
-		
+
 		// Assert
 		Assert.Empty(navigation.ModalStack);
 	}
@@ -106,10 +158,10 @@ public async Task ShowPopupAsync_Shell_WithPopupType_ShowsPopupAndClosesPopup()
 		// Assert
 		Assert.Single(shellNavigation.ModalStack);
 		Assert.IsType<PopupPage>(shellNavigation.ModalStack[0]);
-		
+
 		// Act
 		await navigation.ClosePopupAsync(TestContext.Current.CancellationToken);
-		
+
 		// Assert
 		Assert.Empty(navigation.ModalStack);
 	}
@@ -127,7 +179,7 @@ public void ShowPopupAsync_WithViewType_ShowsPopup()
 		Assert.Single(navigation.ModalStack);
 		Assert.IsType<PopupPage>(navigation.ModalStack[0]);
 	}
-	
+
 	[Fact]
 	public void ShowPopupAsync_WithViewType_SetsCorrectDefaults()
 	{
@@ -138,7 +190,7 @@ public void ShowPopupAsync_WithViewType_SetsCorrectDefaults()
 
 		// Act
 		navigation.ShowPopup(label);
-		
+
 		popupPage = (PopupPage)navigation.ModalStack[0];
 		autogeneratedPopup = (Popup)(((Border)popupPage.Content.Children[0]).Content ?? throw new InvalidOperationException("Border Content cannot be null"));
 
@@ -1276,6 +1328,108 @@ void HandlePopupClosed(object? sender, IPopupResult e)
 			popupClosedTCS.SetResult(e);
 		}
 	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopupAsync_ShouldClosePopupUsingNavigationAndReturnResult()
+	{
+		// Arrange
+
+		if (Application.Current?.Windows[0].Page is not Page page)
+		{
+			throw new InvalidOperationException("Page cannot be null");
+		}
+
+		// Act
+		page.ShowPopup(new MockPopup());
+
+		// Assert
+		Assert.Single(page.Navigation.ModalStack);
+		Assert.IsType<PopupPage>(page.Navigation.ModalStack[0]);
+
+		// Act
+		var popupResult = await page.ClosePopupAsync(TestContext.Current.CancellationToken);
+
+		// Assert
+		Assert.Empty(page.Navigation.ModalStack);
+		Assert.False(popupResult.WasDismissedByTappingOutsideOfPopup);
+	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopupAsync_ShouldClosePopupUsingPageAndReturnResult()
+	{
+		// Arrange
+		if (Application.Current?.Windows[0].Page is not Page page)
+		{
+			throw new InvalidOperationException("Page cannot be null");
+		}
+
+		// Act
+		page.ShowPopup(new MockPopup());
+
+		// Assert
+		Assert.Single(page.Navigation.ModalStack);
+		Assert.IsType<PopupPage>(page.Navigation.ModalStack[0]);
+
+		// Act
+		var popupResult = await page.ClosePopupAsync(page, TestContext.Current.CancellationToken);
+
+		// Assert
+		Assert.Empty(page.Navigation.ModalStack);
+		Assert.False(popupResult.WasDismissedByTappingOutsideOfPopup);
+	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopupAsyncT_ShouldClosePopupUsingNavigationAndReturnResult()
+	{
+		// Arrange
+		const int expectedResult = 2;
+		if (Application.Current?.Windows[0].Page is not Page page)
+		{
+			throw new InvalidOperationException("Page cannot be null");
+		}
+
+		// Act
+		page.ShowPopup(new Popup());
+
+		// Assert
+		Assert.Single(page.Navigation.ModalStack);
+		Assert.IsType<PopupPage>(page.Navigation.ModalStack[0]);
+
+		// Act
+		var popupResult = await page.ClosePopupAsync(expectedResult, TestContext.Current.CancellationToken);
+
+		// Assert
+		Assert.Empty(page.Navigation.ModalStack);
+		Assert.Equal(expectedResult, popupResult.Result);
+		Assert.False(popupResult.WasDismissedByTappingOutsideOfPopup);
+	}
+
+	[Fact(Timeout = (int)TestDuration.Short)]
+	public async Task ClosePopupAsyncT_ShouldClosePopupUsingPageAndReturnResult()
+	{
+		// Arrange
+		const int expectedResult = 2;
+
+		if (Application.Current?.Windows[0].Page is not Page page)
+		{
+			throw new InvalidOperationException("Page cannot be null");
+		}
+
+		// Act
+		page.ShowPopup(new MockPopup());
+
+		// Assert
+		Assert.Single(page.Navigation.ModalStack);
+		Assert.IsType<PopupPage>(page.Navigation.ModalStack[0]);
+
+		// Act
+		var popupResult = await page.ClosePopupAsync(expectedResult, TestContext.Current.CancellationToken);
+
+		// Assert
+		Assert.Empty(page.Navigation.ModalStack);
+		Assert.Equal(expectedResult, popupResult.Result);
+		Assert.False(popupResult.WasDismissedByTappingOutsideOfPopup);
+	}
 }
 
 sealed class ViewWithIQueryAttributable : Button, IQueryAttributable