From b171f5133543526c3d21210a7c7e9dfcc1e8d0fe Mon Sep 17 00:00:00 2001
From: Dan Siegel <me@dansiegel.net>
Date: Fri, 18 Oct 2024 10:14:48 -0600
Subject: [PATCH] chore: adding global region navigation

---
 docs/navigation/regions/index.md |  1 +
 docs/plugins/regions.md          | 98 ++++++++++++++++++++++++++++++++
 docs/plugins/toc.yml             |  2 +
 3 files changed, 101 insertions(+)
 create mode 100644 docs/plugins/regions.md

diff --git a/docs/navigation/regions/index.md b/docs/navigation/regions/index.md
index 23d1b0c..bfc31d4 100644
--- a/docs/navigation/regions/index.md
+++ b/docs/navigation/regions/index.md
@@ -35,3 +35,4 @@ Prism provides guidance on implementing both styles of navigation, focusing on t
 | [Navigation Journal](xref:Navigation.Regions.NavigationJournal) | Use the navigation journal to allow the user to navigate from within the view. |
 | [Passing Parameters](xref:Navigation.Regions.PassingParameters) | Pass data to the view being navigated to. |
 | [View and View Model Participation](xref:Navigation.Regions.ViewViewModelParticipation) | Link your views and view models to the navigation system. |
+| [Global Region Observer](xref:Plugins.ObservableRegions) | Observe and react to Navigation Events globally. |
diff --git a/docs/plugins/regions.md b/docs/plugins/regions.md
new file mode 100644
index 0000000..197d533
--- /dev/null
+++ b/docs/plugins/regions.md
@@ -0,0 +1,98 @@
+---
+uid: Plugins.ObservableRegions
+---
+
+# Getting Started
+
+While it has always been possible to respond to Region Navigation Events such as Navigating, Navigated and NavigationFailed through the IRegionNavigationService, this hasn't been something that is particularly easy to deal with from a global scope. This is in part due to the fact that each Region has it's own Navigation Service. `Prism.Plugin.ObservableRegions` is a new cross platform package from the Prism team exclusively available to Commercial Plus subscribers. For the first time you now have the ability to manage Region Navigation Events from a global context.
+
+## [.NET MAUI](#tab/maui)
+
+```cs
+public static class PrismStartup
+{
+    public static void Configure(PrismAppBuilder builder) =>
+        builder.RegisterTypes(RegisterTypes)
+            .OnInitialized(container => container.ObserveRegionNavigation(RegionNavigationObserver));
+
+    private static void RegisterTypes(IContainerRegistry containerRegistry)
+    {
+        containerRegistry.AddObservableRegions();
+    }
+
+    private static void RegionNavigationObserver(IContainerProvider container, IGlobalRegionNavigationObserver observer) =>
+        observer.Navigation
+            .Where(x => x.Event == RegionNavigationEventType.Failed)
+            .Subscribe(regionEvent => {
+                var logger = container.Resolve<ILogger>();
+                logger.Report(regionEvent.Error!);
+            });
+}
+```
+
+## [WPF](#tab/wpf)
+
+```cs
+public partial class App : Application
+{
+    protected override void RegisterTypes(IContainerRegistry containerRegistry)
+    {
+        containerRegistry.AddObservableRegions();
+    }
+
+    protected override void OnInitialized()
+    {
+        Container.ObserveRegionNavigation(RegionNavigationObserver);
+    }
+
+    private static void RegionNavigationObserver(IContainerProvider container, IGlobalRegionNavigationObserver observer) =>
+        observer.Navigation
+            .Where(x => x.Event == RegionNavigationEventType.Failed)
+            .Subscribe(regionEvent => {
+                var logger = container.Resolve<ILogger>();
+                logger.Report(regionEvent.Error!);
+            });
+}
+```
+
+## [Uno Platform](#tab/uno-platform)
+
+```cs
+public partial class App : Application
+{
+    protected override void RegisterTypes(IContainerRegistry containerRegistry)
+    {
+        containerRegistry.AddObservableRegions();
+    }
+
+    protected override void OnInitialized()
+    {
+        Container.ObserveRegionNavigation(RegionNavigationObserver);
+    }
+
+    private static void RegionNavigationObserver(IContainerProvider container, IGlobalRegionNavigationObserver observer) =>
+        observer.Navigation
+            .Where(x => x.Event == RegionNavigationEventType.Failed)
+            .Subscribe(regionEvent => {
+                var logger = container.Resolve<ILogger>();
+                logger.Report(regionEvent.Error!);
+            });
+}
+```
+
+---
+
+## RegionNavigationEvent
+
+Note that this event does not inherit from PubSubEvent and is not fired from the `IEventAggregator`. The event will give you the following record with access to the Region that is being navigated, the event type, the NavigationContext, the Uri and the ViewName that was being navigated. When the Event Type is null you will also have an Error. The Error will always be null when Navigating and Navigated are the event types.
+
+```cs
+public record RegionNavigationEvent(IRegion Region, RegionNavigationEventType Event, NavigationContext Context, Uri Uri, string Name, Exception? Error = null);
+
+public enum RegionNavigationEventType
+{
+    Navigating,
+    Navigated,
+    Failed
+}
+```
diff --git a/docs/plugins/toc.yml b/docs/plugins/toc.yml
index 75c279d..3aa7ede 100644
--- a/docs/plugins/toc.yml
+++ b/docs/plugins/toc.yml
@@ -2,5 +2,7 @@
   href: essentials/toc.yml
 - name: Logging
   href: logging/toc.yml
+- name: Observable Regions
+  href: regions.md
 - name: Popups
   href: popups.md
\ No newline at end of file