From c63e89db7dd5acbc21c68804902165882ee535e5 Mon Sep 17 00:00:00 2001
From: Shaun Lawrence <17139988+bijington@users.noreply.github.com>
Date: Tue, 15 Oct 2024 20:46:56 +0100
Subject: [PATCH 1/5] Restructure popup and add in the close method details

---
 docs/maui/TOC.yml                             |   6 +-
 .../views/{Popup.md => popup/overview.md}     |  62 +-----
 docs/maui/views/popup/popup-service.md        | 182 ++++++++++++++++++
 3 files changed, 188 insertions(+), 62 deletions(-)
 rename docs/maui/views/{Popup.md => popup/overview.md} (78%)
 create mode 100644 docs/maui/views/popup/popup-service.md

diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml
index c4ced3ab4..63ba65af1 100644
--- a/docs/maui/TOC.yml
+++ b/docs/maui/TOC.yml
@@ -236,7 +236,11 @@ items:
     - name: "MediaElement"
       href: views/MediaElement.md
     - name: "Popup"
-      href: views/Popup.md
+      items:
+        - name: Overview
+          href: views/popup/overview.md
+        - name: "Popup Service"
+          href: views/popup/popup-service.md
     - name: SemanticOrderView
       href: views/semantic-order-view.md
 - name: C# Markup
diff --git a/docs/maui/views/Popup.md b/docs/maui/views/popup/overview.md
similarity index 78%
rename from docs/maui/views/Popup.md
rename to docs/maui/views/popup/overview.md
index 2d32f23d3..d42505f04 100644
--- a/docs/maui/views/Popup.md
+++ b/docs/maui/views/popup/overview.md
@@ -78,67 +78,7 @@ var popup = new Popup
 
 ## Presenting a Popup
 
-Once the `Popup` has been built it can then be presented through the use of our `Popup` extension methods or through the `IPopupService` implementation from this toolkit.
-
-### IPopupService
-
-The .NET MAUI Community Toolkit provides a mechanism to instantiate and present popups in a .NET MAUI application. The popup service is automatically registered with the `MauiAppBuilder` when using the `UseMauiCommunityToolkit` initialization method. This enables you to resolve an `IPopupService` implementation in any part of your application.
-
-The `IPopupService` makes it possible to register a popup view and its associated view model. The ability to show a `Popup` can now be driven by only providing the view model making it possible to keep a clean separation between view and view model.
-
-#### Registering Popups
-
-In order to first use the `IPopupService` to display a popup in your application you will need to register the popup and view model with the `MauiAppBuilder`, this can be done through the use of [Register Popup View and View Model](../extensions/servicecollection-extensions.md#register-popup-view-and-view-model).
-
-#### Displaying Popups
-
-The following example shows how to use the `IPopupService` to create and display a popup in a .NET MAUI application:
-
-```csharp
-public class MyViewModel : INotifyPropertyChanged
-{
-    private readonly IPopupService popupService;
-
-    public MyViewModel(IPopupService popupService)
-    {
-        this.popupService = popupService;
-    }
-
-    public void DisplayPopup()
-    {
-        this.popupService.ShowPopup<UpdatingPopupViewModel>();
-    }
-}
-```
-
-For a more concrete example please refer to our sample application and the example in [`MultiplePopupViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs)
-
-The `IPopupService` also provides methods to handle a result being returned from a Popup as covered in [Returning a result](./Popup.md#returning-a-result).
-
-#### Passing data to a Popup view model
-
-When presenting a Popup we sometimes need to pass data across to the underlying view model to allow for dynamic content to be presented to the user. The `IPopupService` makes this possible through the overloads of the `ShowPopup` and `ShowPopupAsync` methods that takes a `Action<TViewModel> onPresenting` parameter. This parameter has been designed to be framework agnostic and allow you as a developer to drive the loading/passing of data however best fits your architecture.
-
-To extend the previous example of showing a `UpdatingPopupViewModel` and its associated Popup, we can use the `onPresenting` parameter to pass in the number of updates that we wish to perform:
-
-```csharp
-public class MyViewModel : INotifyPropertyChanged
-{
-    private readonly IPopupService popupService;
-
-    public MyViewModel(IPopupService popupService)
-    {
-        this.popupService = popupService;
-    }
-
-    public void DisplayPopup()
-    {
-        this.popupService.ShowPopup<UpdatingPopupViewModel>(onPresenting: viewModel => viewModel.PerformUpdates(10));
-    }
-}
-```
-
-### Extension methods
+Once the `Popup` has been built it can then be presented through the use of our `Popup` extension methods or through the [`IPopupService`](popup-service.md) implementation from this toolkit.
 
 > [!IMPORTANT]
 > A `Popup` can only be displayed from a `Page` or an implementation inheriting from `Page`.
diff --git a/docs/maui/views/popup/popup-service.md b/docs/maui/views/popup/popup-service.md
new file mode 100644
index 000000000..4212073e1
--- /dev/null
+++ b/docs/maui/views/popup/popup-service.md
@@ -0,0 +1,182 @@
+---
+title: Popup - .NET MAUI Community Toolkit
+author: bijington
+description: The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.
+ms.date: 04/12/2022
+---
+
+# PopupService
+
+The PopupService provides a mechanism for displaying [Popups](overview.md) within an application using the MVVM pattern.
+
+The following sections will incrementally build on how to use the `PopupService` in a .NET MAUI application.
+
+## Creating a Popup
+
+In order to use the PopupService to present or close a Popup the Popup must first be registered. Based on the steps in [Defining your popup](popup-service.md#defining-your-popup) the following can be created.
+
+```xaml
+<toolkit:Popup 
+    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"
+    xmlns:viewModels="clr-namespace:MyProject.ViewModels"
+    x:Class="MyProject.Popups.NamePopup"
+    x:DataType="viewModels:NamePopupViewModel">
+
+    <VerticalStackLayout>
+        <Label Text="What is your name?" />
+        <Entry Text="{Binding Name}" />
+
+        <Button Text="Save" Command="{Binding SaveCommand}" />
+        <Button Text="Cancel" Command="{Binding CancelCommand}" />
+    </VerticalStackLayout>
+    
+</toolkit:Popup>
+```
+
+```csharp
+using CommunityToolkit.Maui.Views;
+using MyProject.ViewModels;
+
+namespace MyProject.Popups;
+
+public partial class NamePopup : Popup
+{
+    public NamePopup(NamePopupViewModel namePopupViewModel)
+    {
+        InitializeComponent();
+        BindingContext = namePopupViewModel;
+    }
+}
+```
+
+```csharp
+public class NamePopupViewModel : ObservableObject
+{
+    [ObservableProperty]
+    string name = "";
+
+    readonly IPopupService popupService;
+
+    public NamePopupViewModel(IPopupService popupService)
+    {
+        this.popupService = popupService;
+    }
+
+    void OnCancel()
+    {
+    }
+
+    [RelayCommand(CanExecute = nameof(CanSave))]
+    void OnSave()
+    {
+    }
+
+    bool CanSave() => string.IsNullOrWhitespace(Name) is false;
+}
+```
+
+## Registering a Popup
+
+In order to first use the `IPopupService` to display a popup in your application you will need to register the popup and view model with the `MauiAppBuilder`, this can be done through the use of [Register Popup View and View Model](../../extensions/servicecollection-extensions.md#register-popup-view-and-view-model).
+
+Based on the example above the following code can be added to the MauiProgram.cs file.
+
+```csharp
+builder.Services.AddTransientPopup<NamePopup, NamePopupViewModel>();
+```
+
+## Presenting a Popup
+
+The .NET MAUI Community Toolkit provides a mechanism to instantiate and present popups in a .NET MAUI application. The popup service is automatically registered with the `MauiAppBuilder` when using the `UseMauiCommunityToolkit` initialization method. This enables you to resolve an `IPopupService` implementation in any part of your application.
+
+The `IPopupService` makes it possible to register a popup view and its associated view model. The ability to show a `Popup` can now be driven by only providing the view model making it possible to keep a clean separation between view and view model.
+
+The following example shows how to use the `IPopupService` to create and display a popup in a .NET MAUI application:
+
+```csharp
+public class MyViewModel : INotifyPropertyChanged
+{
+    private readonly IPopupService popupService;
+
+    public MyViewModel(IPopupService popupService)
+    {
+        this.popupService = popupService;
+    }
+
+    public void DisplayPopup()
+    {
+        this.popupService.ShowPopup<NamePopupViewModel>();
+    }
+}
+```
+
+For a more concrete example please refer to our sample application and the example in [`MultiplePopupViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs)
+
+The `IPopupService` also provides methods to handle a result being returned from a Popup as covered in [Returning a result](./Popup.md#returning-a-result).
+
+## Passing data to a Popup view model
+
+When presenting a Popup we sometimes need to pass data across to the underlying view model to allow for dynamic content to be presented to the user. The `IPopupService` makes this possible through the overloads of the `ShowPopup` and `ShowPopupAsync` methods that takes a `Action<TViewModel> onPresenting` parameter. This parameter has been designed to be framework agnostic and allow you as a developer to drive the loading/passing of data however best fits your architecture.
+
+To extend the previous example of showing a `NamePopupViewModel` and its associated Popup, we can use the `onPresenting` parameter to pass in the users name:
+
+```csharp
+public class MyViewModel : INotifyPropertyChanged
+{
+    private readonly IPopupService popupService;
+
+    public MyViewModel(IPopupService popupService)
+    {
+        this.popupService = popupService;
+    }
+
+    public void DisplayPopup()
+    {
+        this.popupService.ShowPopup<UpdatingPopupViewModel>(onPresenting: viewModel => viewModel.Name = "Shaun");
+    }
+}
+```
+
+## Closing a Popup
+
+The `PopupService` provides the `ClosePopup` and `ClosePopupAsync` methods that make it possible to close a `Popup` from a view model.
+
+### Programmatically closing a Popup
+
+Expanding on the previous example the following implementation can be added to the `OnCancel` method:
+
+```csharp
+[RelayCommand]
+void OnCancel()
+{
+    popupService.ClosePopup();
+}
+```
+
+This will result in the most recently displayed `Popup` being closed.
+
+### Returning a result
+
+When closing a `Popup` it is possible to return a result to the caller that presented the `Popup`.
+
+Expanding on the previous example the following implementation can be added to the `OnSave` method:
+
+```csharp
+[RelayCommand(CanExecute = nameof(CanSave))]
+void OnSave()
+{
+    popupService.ClosePopup(Name);
+}
+```
+
+This will result in the most recently displayed `Popup` being closed and the caller being return the value in `Name`.
+
+## Examples
+
+You can find an example of this feature in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Views/).
+
+## API
+
+You can find the source code for `Popup` over on the [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/tree/main/src/CommunityToolkit.Maui/Views/Popup).

From 6d998cc3f73857107e341921f858b9c42112bdb9 Mon Sep 17 00:00:00 2001
From: Shaun Lawrence <17139988+bijington@users.noreply.github.com>
Date: Tue, 15 Oct 2024 20:49:57 +0100
Subject: [PATCH 2/5] More detail

---
 docs/maui/views/popup/popup-service.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/maui/views/popup/popup-service.md b/docs/maui/views/popup/popup-service.md
index 4212073e1..9d63ad9f7 100644
--- a/docs/maui/views/popup/popup-service.md
+++ b/docs/maui/views/popup/popup-service.md
@@ -7,13 +7,15 @@ ms.date: 04/12/2022
 
 # PopupService
 
-The PopupService provides a mechanism for displaying [Popups](overview.md) within an application using the MVVM pattern.
+The `PopupService` provides a mechanism for displaying [Popups](overview.md) within an application using the MVVM pattern.
 
 The following sections will incrementally build on how to use the `PopupService` in a .NET MAUI application.
 
 ## Creating a Popup
 
-In order to use the PopupService to present or close a Popup the Popup must first be registered. Based on the steps in [Defining your popup](popup-service.md#defining-your-popup) the following can be created.
+In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Defining your popup](popup-service.md#defining-your-popup) the following can be created.
+
+The XAML contents of the `Popup` can be defined as:
 
 ```xaml
 <toolkit:Popup 
@@ -35,6 +37,8 @@ In order to use the PopupService to present or close a Popup the Popup must firs
 </toolkit:Popup>
 ```
 
+The C# contents of the `Popup` can be defined as:
+
 ```csharp
 using CommunityToolkit.Maui.Views;
 using MyProject.ViewModels;
@@ -51,6 +55,8 @@ public partial class NamePopup : Popup
 }
 ```
 
+The backing view model for the `Popup` can be defined as:
+
 ```csharp
 public class NamePopupViewModel : ObservableObject
 {
@@ -112,6 +118,15 @@ public class MyViewModel : INotifyPropertyChanged
 }
 ```
 
+Alternatively the caller can await the ShowPopupAsync method in order to handle a [result being returned](#returning-a-result). The `DisplayPopup` method can be rewritten as:
+
+```csharp
+public void DisplayPopup()
+{
+    var name = await this.popupService.ShowPopupAsync<NamePopupViewModel>();
+}
+```
+
 For a more concrete example please refer to our sample application and the example in [`MultiplePopupViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs)
 
 The `IPopupService` also provides methods to handle a result being returned from a Popup as covered in [Returning a result](./Popup.md#returning-a-result).

From 847bbc402b6eb53a306edd006ea1fad0e7ee888a Mon Sep 17 00:00:00 2001
From: Shaun Lawrence <17139988+bijington@users.noreply.github.com>
Date: Tue, 17 Dec 2024 20:40:22 +0000
Subject: [PATCH 3/5] Fix some build issues

---
 docs/maui/views/popup/overview.md      | 4 ++--
 docs/maui/views/popup/popup-service.md | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/maui/views/popup/overview.md b/docs/maui/views/popup/overview.md
index d42505f04..de0377492 100644
--- a/docs/maui/views/popup/overview.md
+++ b/docs/maui/views/popup/overview.md
@@ -10,7 +10,7 @@ ms.date: 04/12/2022
 Popups are a very common way of presenting information to a user that relates to their current task. Operating systems provide a way to show a message and require a response from the user, these alerts are typically restrictive in terms of the content a developer can provide and also the layout and appearance.
 
 > [!NOTE]
-> If you wish to present something to the user that is more subtle then checkout our [Toast](../alerts/toast.md) and [Snackbar](../alerts/snackbar.md) options.
+> If you wish to present something to the user that is more subtle then checkout our [Toast](../../alerts/toast.md) and [Snackbar](../../alerts/snackbar.md) options.
 
 The `Popup` view allows developers to build their own custom UI and present it to their users.
 
@@ -22,7 +22,7 @@ A `Popup` can be created in XAML or C#:
 
 #### Including the XAML namespace
 
-[!INCLUDE [XAML usage guidance](../includes/xaml-usage.md)]
+[!INCLUDE [XAML usage guidance](../../includes/xaml-usage.md)]
 
 #### Defining your Popup
 
diff --git a/docs/maui/views/popup/popup-service.md b/docs/maui/views/popup/popup-service.md
index 9d63ad9f7..e36a70372 100644
--- a/docs/maui/views/popup/popup-service.md
+++ b/docs/maui/views/popup/popup-service.md
@@ -1,5 +1,5 @@
 ---
-title: Popup - .NET MAUI Community Toolkit
+title: PopupService - .NET MAUI Community Toolkit
 author: bijington
 description: The PopupService provides a mechanism for displaying Popups within an application using the MVVM pattern.
 ms.date: 04/12/2022
@@ -13,7 +13,7 @@ The following sections will incrementally build on how to use the `PopupService`
 
 ## Creating a Popup
 
-In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Defining your popup](popup-service.md#defining-your-popup) the following can be created.
+In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Defining your popup](./overview.md#defining-your-popup) the following can be created.
 
 The XAML contents of the `Popup` can be defined as:
 
@@ -129,7 +129,7 @@ public void DisplayPopup()
 
 For a more concrete example please refer to our sample application and the example in [`MultiplePopupViewModel`](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs)
 
-The `IPopupService` also provides methods to handle a result being returned from a Popup as covered in [Returning a result](./Popup.md#returning-a-result).
+The `IPopupService` also provides methods to handle a result being returned from a Popup as covered in [Returning a result](./popup-service.md#returning-a-result).
 
 ## Passing data to a Popup view model
 

From 7edc8009121846560e5998c7599ecaa79f846194 Mon Sep 17 00:00:00 2001
From: Shaun Lawrence <17139988+bijington@users.noreply.github.com>
Date: Tue, 17 Dec 2024 20:43:42 +0000
Subject: [PATCH 4/5] Undo rename

---
 docs/maui/TOC.yml                               | 2 +-
 docs/maui/views/popup/{overview.md => Popup.md} | 0
 docs/maui/views/popup/popup-service.md          | 4 ++--
 3 files changed, 3 insertions(+), 3 deletions(-)
 rename docs/maui/views/popup/{overview.md => Popup.md} (100%)

diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml
index 63ba65af1..ce9e968fe 100644
--- a/docs/maui/TOC.yml
+++ b/docs/maui/TOC.yml
@@ -238,7 +238,7 @@ items:
     - name: "Popup"
       items:
         - name: Overview
-          href: views/popup/overview.md
+          href: views/popup/Popup.md
         - name: "Popup Service"
           href: views/popup/popup-service.md
     - name: SemanticOrderView
diff --git a/docs/maui/views/popup/overview.md b/docs/maui/views/popup/Popup.md
similarity index 100%
rename from docs/maui/views/popup/overview.md
rename to docs/maui/views/popup/Popup.md
diff --git a/docs/maui/views/popup/popup-service.md b/docs/maui/views/popup/popup-service.md
index e36a70372..f4acec7df 100644
--- a/docs/maui/views/popup/popup-service.md
+++ b/docs/maui/views/popup/popup-service.md
@@ -7,13 +7,13 @@ ms.date: 04/12/2022
 
 # PopupService
 
-The `PopupService` provides a mechanism for displaying [Popups](overview.md) within an application using the MVVM pattern.
+The `PopupService` provides a mechanism for displaying [Popups](./Popup.md) within an application using the MVVM pattern.
 
 The following sections will incrementally build on how to use the `PopupService` in a .NET MAUI application.
 
 ## Creating a Popup
 
-In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Defining your popup](./overview.md#defining-your-popup) the following can be created.
+In order to use the `PopupService` to present or close a `Popup` the `Popup` must first be registered. Based on the steps in [Defining your popup](./Popup.md#defining-your-popup) the following can be created.
 
 The XAML contents of the `Popup` can be defined as:
 

From 9880714b12e4f70bcab124ecb8ec58668c7abfef Mon Sep 17 00:00:00 2001
From: Shaun Lawrence <17139988+bijington@users.noreply.github.com>
Date: Tue, 17 Dec 2024 20:47:12 +0000
Subject: [PATCH 5/5] Another attempt at fixing links

---
 docs/maui/TOC.yml                            | 4 ++--
 docs/maui/views/{popup => }/Popup.md         | 4 ++--
 docs/maui/views/{popup => }/popup-service.md | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)
 rename docs/maui/views/{popup => }/Popup.md (98%)
 rename docs/maui/views/{popup => }/popup-service.md (98%)

diff --git a/docs/maui/TOC.yml b/docs/maui/TOC.yml
index ce9e968fe..2ac5c839d 100644
--- a/docs/maui/TOC.yml
+++ b/docs/maui/TOC.yml
@@ -238,9 +238,9 @@ items:
     - name: "Popup"
       items:
         - name: Overview
-          href: views/popup/Popup.md
+          href: views/Popup.md
         - name: "Popup Service"
-          href: views/popup/popup-service.md
+          href: views/popup-service.md
     - name: SemanticOrderView
       href: views/semantic-order-view.md
 - name: C# Markup
diff --git a/docs/maui/views/popup/Popup.md b/docs/maui/views/Popup.md
similarity index 98%
rename from docs/maui/views/popup/Popup.md
rename to docs/maui/views/Popup.md
index de0377492..d42505f04 100644
--- a/docs/maui/views/popup/Popup.md
+++ b/docs/maui/views/Popup.md
@@ -10,7 +10,7 @@ ms.date: 04/12/2022
 Popups are a very common way of presenting information to a user that relates to their current task. Operating systems provide a way to show a message and require a response from the user, these alerts are typically restrictive in terms of the content a developer can provide and also the layout and appearance.
 
 > [!NOTE]
-> If you wish to present something to the user that is more subtle then checkout our [Toast](../../alerts/toast.md) and [Snackbar](../../alerts/snackbar.md) options.
+> If you wish to present something to the user that is more subtle then checkout our [Toast](../alerts/toast.md) and [Snackbar](../alerts/snackbar.md) options.
 
 The `Popup` view allows developers to build their own custom UI and present it to their users.
 
@@ -22,7 +22,7 @@ A `Popup` can be created in XAML or C#:
 
 #### Including the XAML namespace
 
-[!INCLUDE [XAML usage guidance](../../includes/xaml-usage.md)]
+[!INCLUDE [XAML usage guidance](../includes/xaml-usage.md)]
 
 #### Defining your Popup
 
diff --git a/docs/maui/views/popup/popup-service.md b/docs/maui/views/popup-service.md
similarity index 98%
rename from docs/maui/views/popup/popup-service.md
rename to docs/maui/views/popup-service.md
index f4acec7df..b4cfe1e23 100644
--- a/docs/maui/views/popup/popup-service.md
+++ b/docs/maui/views/popup-service.md
@@ -85,7 +85,7 @@ public class NamePopupViewModel : ObservableObject
 
 ## Registering a Popup
 
-In order to first use the `IPopupService` to display a popup in your application you will need to register the popup and view model with the `MauiAppBuilder`, this can be done through the use of [Register Popup View and View Model](../../extensions/servicecollection-extensions.md#register-popup-view-and-view-model).
+In order to first use the `IPopupService` to display a popup in your application you will need to register the popup and view model with the `MauiAppBuilder`, this can be done through the use of [Register Popup View and View Model](../extensions/servicecollection-extensions.md#register-popup-view-and-view-model).
 
 Based on the example above the following code can be added to the MauiProgram.cs file.