docs: Update existing reference navigation docs

doc/Reference/Navigation/Design.md

@@ -19,42 +19,22 @@ There are `INavigator` extension methods that accept a variety of parameters, de
 
 ## Navigation Controls
 
-An application typically has one or more views responsible for controlling navigation. Eg a Frame that navigates between pages, or a TabBar that switches tabs
+An application typically has one or more views responsible for controlling navigation. For example, a Frame that navigates between pages, or a TabBar that switches tabs
 
-Navigation controls can be categorized in three distinct groups with different Navigation goals.
+Navigation controls can be categorized into three distinct groups with different Navigation goals.
 
 | Content-Based        | Has a content area that's used to display the current view                                                             |
 |----------------------|------------------------------------------------------------------------------------------------------------------------|
 | ContentControl       | Navigation creates an instance of a control and sets it as the Content                                                 |
-| Panel (eg Grid)      | Navigation sets a child element to Visible, hiding any previously visible child. Two scenarios:<br>	- An existing child is found. The child is set to Visible<br>	- No child is found. A new instance of a control is created and added to the Panel. The new instance is set to visible<br>Note that when items are hidden, they're no removed from the visual tree |
-| Frame                | Forward navigation adds a new page to the stack based <br>Backward navigation pops the current page off the stack<br>Combination eg forward navigation and clear back stack |
+| Panel (eg Grid)      | Navigation sets a child element to Visible, hiding any previously visible child. Two scenarios:<br>	- An existing child is found. The child is set to Visible<br>	- No child is found. A new instance of a control is created and added to the Panel. The new instance is set to visible<br>Note that when items are hidden, they're not removed from the visual tree |
+| Frame                | Forward navigation adds a new page to the stack-based <br>Backward navigation pops the current page off the stack<br>Combination, for example, forward navigation and clear back stack |
 |                      |                                                                                                                        |
-| **Selection-Based**      | **Has selectable items**                                                                                                 |
+| **Selection-Based**      | **Has selectable items**                                                                                           |
 | NavigationView       | Navigation selects the NavigationViewitem with the correct Region.Name set                                             |
 | TabBar               | Navigation selects the TabBarItem with the correct Region.Name set                                                     |
 |                      |                                                                                                                        |
-| **Prompt-Based (Modal)** | **Modal style prompt, typically for capturing input from user**                                                            |
+| **Prompt-Based (Modal)** | **Modal style prompt, typically for capturing input from user**                                                    |
 | ContentDialog        | Forward navigation opens a content dialog <br>Backward navigation closes the dialog                                    |
 | MessageDialog        | Forward navigation opens a MessageDialog<br>Backward navigation closes the MessageDialog                               |
 | Popup                | Forward navigation opens the popup<br>Backward navigation closes the popup                                             |
-| Flyout               | Forward navigation opens the flyout<br>Backward navigation closes the flyout                                           |
-
-## Regions
-A region is the abstraction of the view responsible for handling navigation.
-
-Regions are structured into a logical hierarchical representation that shadows the navigation-aware controls in the visual hierarchy. The hierarchy allows navigation requests to be propagated up to parent and down to child regions as required.
-
-Regions are specified by setting Region.Attached="true" on a navigation control (eg Frame, ContentControl, Grid).
-
-```csharp
-<ContentControl uen:Region.Attached="true" />
-```
-
-Pushing a view to this region:
-	`navigator.NavigateRouteAsync(this,"ProductDetails");`
-or
-	`navigator.NavigateViewAsync<ProductDetailsControl>(this);`
-or
-	`navigator.NavigateViewModelAsync<ProductDetailsViewModel(this);`
-or
-    `navigator.NavigateDataAsync(this, selectedProduct);`
+| Flyout               | Forward navigation opens the flyout<br>Backward navigation closes the flyout                                           |

doc/Reference/Navigation/Navigation.md

@@ -1,6 +1,7 @@
 ---
 uid: Reference.Navigation.Overview
 ---
+
 # Navigation Reference
 
 The pages in this section provide extended reference information for Navigation-related features.

doc/Reference/Navigation/NavigationRegion.md

@@ -1,15 +1,28 @@
 ---
 uid: Reference.Navigation.Regions
 ---
+
 # What is a Navigation Region
 
+## Regions
+
+A region is a part of the user interface that manages navigation.
+
+Regions are organized in a hierarchy that mirrors the structure of the navigation controls in the user interface. This hierarchy allows navigation commands to move up to parent regions or down to child regions as needed.
+
+To specify a region, you set `Region.Attached="true"` on a navigation control (like Frame, ContentControl, or Grid).
+
+```xml
+<ContentControl uen:Region.Attached="true" />
+```
+
 ## Region Name
 
-Regions can be named by specifying the Region.Name="XXX" property.
+You can name a region by setting the `Region.Name="RegionName"` property.
 
-For selection-based regions, the selectable items (NavigationViewItem, TabBarItem, …) are identified using the Region.Name property
+In selection-based regions, the selectable items (like `NavigationViewItem`, `TabBarItem`, etc.) are identified using the Region.Name property.
 
-```csharp
+```xml
 <muxc:NavigationView uen:Region.Attached="true">
 	<muxc:NavigationView.MenuItems>
 		<muxc:NavigationViewItem Content="Products" uen:Region.Name="Products" />
@@ -20,6 +33,20 @@ For selection-based regions, the selectable items (NavigationViewItem, TabBarIte
 ```
 
 Switching selected item:
-	`naviator.NavigateRouteAsync(this,"Deals");`
 
-- Define what a navigation region is and how the hierarchy of regions is created with the Region.Attached property
+```csharp
+navigator.NavigateRouteAsync(this, "Deals");
+```
+or
+```csharp
+navigator.NavigateViewAsync<DealsControl>(this);
+```
+or
+```csharp
+navigator.NavigateViewModelAsync<DealsViewModel>(this);
+```
+or
+```csharp
+navigator.NavigateDataAsync(this, selectedDeal);
+```
+

doc/Reference/Navigation/NavigationRequestHandler.md

@@ -1,6 +1,7 @@
 ---
 uid: Reference.Navigation.RequestHandler
 ---
+
 # Building a Custom Request Handler
 
 - Show how to create a custom NavigationRequestHandler that will intercept event on a control in order to trigger navigation.

doc/Reference/Navigation/Qualifiers.md

@@ -4,10 +4,15 @@ uid: Reference.Navigation.Qualifiers
 
 # Navigation Qualifiers
 
-| Qualifier |                                                              | Example          |                                                              |
-|-----------|--------------------------------------------------------------|------------------|--------------------------------------------------------------|
-| ""        | Navigate to page in frame, or open popup                     | "Home"           | Navigate to the HomePage                                     |
-| /         | Forward request to the root region                           | "/"<br>"/Login"  | Navigate to the default route at the root of navigation<br>Navigate to LoginPage at the root of navigation |
-| ./        | Forward request to child region                              | "./Info/Profile" | Navigates to the Profile view in the child region named Info |
-| !         | Open a dialog or flyout                                      | "!Cart"          | Shows the Cart flyout                                        |
-| -         | Back (Frame), Close (Dialog/Flyout) or respond to navigation | "-"<br>"--Profile"<br>"-/Login" | Navigate back one page (in a frame)<br>Navigate to Profile page and remove two pages from backstack<br>Navigate to Login page and clear backstack |
+Navigation qualifiers can be utilized to make navigating easier and smoother:
+
+| Qualifier | Description                                     | Example             | Example Usage                                                |
+|-----------|-------------------------------------------------|---------------------|--------------------------------------------------------------|
+| ""        | Navigate to page in frame or open popup        | "Home"              | Navigate to the `HomePage`                                     |
+| /         | Forward request to the root region              | "/"<br>"/Login"     | Navigate to the default route at the root of navigation<br>Navigate to `LoginPage` at the root of navigation |
+| ./        | Forward request to child region                 | "./Info/Profile"    | Navigate to the Profile view in the child region named Info |
+| !         | Open a dialog or flyout                         | "!Cart"             | Shows the Cart flyout                                        |
+| -         | Back (Frame), Close (Dialog/Flyout), or respond to navigation | "-"<br>"--Profile"<br>"-/Login" | Navigate back one page (in a frame)<br>Navigate to `ProfilePage` and remove two pages from back stack<br>Navigate to `LoginPage` and clear back stack |
+
+> [!NOTE]
+> Besides using qualifiers as a string as part of the route specification, a `Qualifiers` class is also providaded under the `Uno.Extensions.Navigation` namespace and can be specified when navigating, for example, `await navigator.NavigateViewModelAsync<MainViewModel>(this, Qualifiers.ClearBackStack);`.

doc/Reference/Navigation/RouteMap.md

@@ -1,25 +1,20 @@
 ---
 uid: Reference.Navigation.RouteMap
 ---
+
 # What is a RouteMap
 
 ## RouteMap
 
-In order for navigation to support both view and viewmodel based navigation it is necessary to have some way to define a mapping, or association, between a view and viewmodel (for example MainPage is mapped to MainViewModel, and vice versa).  However, given the different intents and behaviours we needed to support, navigation supports a more complex mapping that is referred to as a RouteMap.
+To support navigation with both View and ViewModel, we need a way to define a mapping between them (e.g., MainPage maps to MainViewModel). However, because of the various intents and behaviors we must support, our navigation system uses a more complex mapping called a RouteMap.
 
 A RouteMap is made up of the following components:
 
 | Component  | Description                                                                                                                      |
 |------------|----------------------------------------------------------------------------------------------------------------------------------|
-| Path       | The name of the route. When processing a NavigationRequest the Base is used to look up the RouteMap with the corresponding Path.<br>This is used to match to the Region.Name attribute for PanelVisibilityNavigator, NavigationViewNavigator and TabBarNavigator<br>NavigateRouteAsync(sender, Path) to navigate to the RouteMap with matching Path.<br>That Path is also used to populate the deep link at any point in the application. |
-| View       | The type of view to be created (or in the case of Frame, navigated to)<br>NavigateViewAsync<Tview>(sender) to navigate to the RouteMap with the matching View (type) |
-| ViewModel  | The type of view model to be created, and set as DataContext for the current view of the region<br>NavigateViewModelAsync<TViewModel>(sender) to navigate to the RouteMap with the matching ViewModel (type) |
-| Data       | The type of data being sent in the navigation request<br>NavigateDataAsync(sender, Data: data) to navigate to the RouteMap with matching Data (type) |
-| ResultData | The type of data to be returned in the response to the navigation request<br>NavigateForResultAsync<TResultData>(sender) to navigate to the RouteMap with matching ResultData(type) |
+| Path       | The name of the route. When processing a NavigationRequest the Base is used to look up the RouteMap with the corresponding Path.<br>This is used to match to the Region.Name attribute for `PanelVisibilityNavigator`, `NavigationViewNavigator` and `TabBarNavigator`<br>`NavigateRouteAsync(sender, Path)` to navigate to the RouteMap with matching Path.<br>That Path is also used to populate the deep link at any point in the application. |
+| View       | The type of view to be created (or in the case of `Frame`, navigated to)<br>`NavigateViewAsync<TView>(sender)` to navigate to the RouteMap with the matching View (type) |
 | IsDefault  | Determines which child route should, if any, be used as the default route                                                        |
+| DependsOn  | Enables establishing a dependency between two views. This argument expects a route name and ensures that when navigating to a view with dependencies, the dependent view will be navigated to first before opening the requested view
 | Init       | Callback function to be invoked prior to navigation for a particular route                                                       |
-| ToQuery    | Callback function to convert a data object into query parameters (eg Product -> [{"ProductId", "1234"}] )                        |
-| FromQuery  | Callback function to convert query parameters into a data object (eg [{"ProductId", "1234"}] -> Product )                        |
-| Nested     | Child routes - currently only used to specify default views for nested regions                                                   |
-
-- Explain what a RouteMap is and how it's used to define the route hierarchy in the app
+| Nested     | Child routes - currently only used to specify default views for nested regions                                                   |

doc/Reference/Navigation/ViewMap.md

@@ -1,6 +1,18 @@
 ---
 uid: Reference.Navigation.ViewMap
 ---
+
 # What is a ViewMap
 
-- Define what a viewmap is and the relationship between view, viewmodel and datamap
+When registering routes, we can take advantage of the `ViewMap` object and its variations `DataViewMap` and `ResultDataViewMap`, to associate Views with ViewModels, specify the type of parameters ViewModels may take, and specify the type of return coming from a navigation.
+
+## ViewMap
+
+| Component      | Description          | Example |
+|----------------|----------------------|---------|
+| View           | The type of the View | `new ViewMap(typeof(MainPage))`<br><br>Alternatively can be specified as a generic argument: `new ViewMap<MainPage>()` |
+| ViewSelector   |         ?             | ? |
+| ViewModel      | The type of the ViewModel being associated with the View | `new ViewMap(typeof(MainPage), ViewModel: typeof(MainViewModel))`<br><br>Alternatively can be specified as a generic argument: `new ViewMap<MainPage, MainViewModel>()` |
+| Data           | A `DataMap<T>` to be injected into the ViewModel during navigation<br><br>Alternatively `DataViewMap` can be used | `new ViewMap<MainPage, MainViewModel>(Data: new DataMap<MyObject>)`<br><br>`new DataViewMap<MainPage, MainViewModel, MyObject>()` |
+| ResultData     | Define an association between the view and the type of data being requested<br><br>Alternatively `ResultDataViewMap` can be used | `new ViewMap<MainPage, MainViewModel>(ResultData: typeof(MyObject))`<br><br>`new ResultDataViewMap<MainPage, MainViewModel, MyObject>()` |
+| ViewAttributes |         ?             | ? |

doc/toc.yml

@@ -70,20 +70,20 @@
           href: Reference/Reactive/Architecture.md
         - name: Analysis rules
           href: Reference/Reactive/rules.md
-    # - name: Navigation
-    #   href: Reference/Navigation/Navigation.md
-    #   items:
-    #     - name: Design
-    #       href: Reference/Navigation/Design.md
-    #     - name: Navigation Region
-    #       href: Reference/Navigation/NavigationRegion.md
-    #     - name: Qualifiers
-    #       href: Reference/Navigation/Qualifiers.md
-    #     - name: View Map
-    #       href: Reference/Navigation/ViewMap.md
-    #     - name: Route Map
-    #       href: Reference/Navigation/RouteMap.md
-    #     - name: Implement INavigator
-    #       href: Reference/Navigation/Navigator.md
-    #     - name: Implement IRequestHandler
-    #       href: Reference/Navigation/NavigationRequestHandler.md
+    - name: Navigation
+      href: xref:Reference.Navigation.Overview
+      items:
+        - name: Design
+          href: xref:Reference.Navigation.Design
+        - name: Navigation Region
+          href: xref:Reference.Navigation.Regions
+        - name: Qualifiers
+          href: xref:Reference.Navigation.Qualifiers
+        - name: View Map
+          href: xref:Reference.Navigation.ViewMap
+        - name: Route Map
+          href: xref:Reference.Navigation.RouteMap
+        - name: Implement INavigator
+          href: xref:Reference.Navigation.Navigator
+        - name: Implement IRequestHandler
+          href: xref:Reference.Navigation.RequestHandler