improve bit Boilerplate docs (#11591)

Author: ysmoradi

src/Templates/Boilerplate/Bit.Boilerplate/.docs/22- Messaging.md

@@ -546,7 +546,20 @@ private async Task ShowNotification()
 
 ---
 
-## 7. Dashboard Data Changed Example
+## 7. Testing Push Notifications - Understanding the Four Scenarios
+
+When testing push notifications, you must consider **four distinct scenarios** based on the app state when the notification is sent and when the user taps on it:
+
+1. **Scenario 1**: The app was **closed** when the notification was sent, and the app was **still closed** when the user tapped on the notification.
+2. **Scenario 2**: The app was **closed** when the notification was sent, but the app was **already open** when the user tapped on the notification.
+3. **Scenario 3**: The app was **open** when the notification was sent, but the app was **closed** when the user tapped on the notification.
+4. **Scenario 4**: The app was **open** when the notification was sent, and the app was **still open** when the user tapped on the notification.
+
+The codebase includes specialized handling across all platforms to manage these scenarios correctly. The implementation uses different entry points and data extraction methods depending on whether the app is starting up, already running, or being brought back from the background.
+
+---
+
+## 8. Dashboard Data Changed Example
 
 Another common scenario is notifying all authenticated clients when data changes.
 

src/Templates/Boilerplate/Bit.Boilerplate/.github/copilot-instructions.md

@@ -128,7 +128,7 @@ After applying changes, you **MUST** verify the integrity of the application.
 Example 1: `OnClick="WrapHandled(MyMethod)"` instead of `OnClick="MyMethod"`.
 Example 2: `OnClick="WrapHandled(async () => await MyMethod())"` instead of `OnClick="async () => await MyMethod()"`.
 16. **Use OData Query Options**: Leverage `[EnableQuery]` and `ODataQueryOptions` for efficient data filtering and pagination.
-17. **Follow Mapperly Conventions**: Use partial static classes and extensions methods with Mapperly for high-performance object mapping.
+17. **Follow Mapperly Conventions**: Use **partial static classes and extensions methods** with Mapperly for high-performance object mapping.
 18. **Handle Concurrency**: Always use `ConcurrencyStamp` for optimistic concurrency control in update and delete operations.
 
 ## Instructions for adding new model/entity to ef-core DbContext / Database

src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md

@@ -1083,6 +1083,12 @@ At the end of Stage 21, ask: **"Do you have any questions about .NET MAUI, nativ
      - Find `PushNotificationService` implementation
      - Show examples of sending push notifications with deep links
      - Explain how to handle notification clicks on the client side
+   - **Explain** that in order to test push notifications, the following scenarios must be considered:
+     1. The time that push notification was sent, the app was closed already, and when the user tapped on the notification to open the app, the app was still closed.
+     2. The time that push notification was sent, the app was closed already, but when the user tapped on the notification, the app was already open.
+     3. The time that push notification was sent, the app was open, but the time that user tapped on the notification, the app was closed.
+     4. The time that push notification was sent, the app was open, and the time that user tapped on the notification, the app was still open.
+     Explain that if some similar codes exists in the codebase, they are used to handle these 4 different scenarios across platforms.
 <!--#endif-->
 
 ---

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Common/Prompt.razor

@@ -1,5 +1,7 @@
 @inherits AppComponentBase
 
+@* This component gets shown by the PromptService to prompt the user for input. *@
+
 <section>
     <BitStack Gap="0">
         <BitStack Horizontal AutoHeight Class="header-stack">

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Layout/AppAiChatPanel.razor.cs

@@ -158,6 +158,8 @@ private async Task StartChannel()
     {
         channel = Channel.CreateUnbounded<string>(new() { SingleReader = true, SingleWriter = true });
 
+        // The following code streams user's input messages to the server and processes the streamed responses.
+        // It keeps the chat ongoing until CurrentCancellationToken is cancelled.
         await foreach (var response in hubConnection.StreamAsync<string>("Chatbot",
                                                                          new StartChatbotRequest()
                                                                          {

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Pages/Identity/SignIn/SignInPanel.razor.cs

@@ -211,7 +211,7 @@ private async Task SocialSignIn(string provider)
         try
         {
             pubSubUnsubscribe?.Invoke();
-            pubSubUnsubscribe = PubSubService.Subscribe(ClientPubSubMessages.SOCIAL_SIGN_IN, async (uriString) =>
+            pubSubUnsubscribe = PubSubService.Subscribe(ClientPubSubMessages.SOCIAL_SIGN_IN_CALLBACK, async (uriString) =>
             {
                 // Check out SignInModalService for more details
                 var uri = uriString!.ToString();

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Pages/Identity/SignUp/SignUpPage.razor.cs

@@ -90,7 +90,7 @@ private async Task SocialSignUp(string provider)
     {
         try
         {
-            pubSubUnsubscribe = PubSubService.Subscribe(ClientPubSubMessages.SOCIAL_SIGN_IN, async (uriString) =>
+            pubSubUnsubscribe = PubSubService.Subscribe(ClientPubSubMessages.SOCIAL_SIGN_IN_CALLBACK, async (uriString) =>
             {
                 // Social sign-in creates a new user automatically, so we only need to navigate to the sign-in page to automatically sign-in the user by provided OTP.
                 NavigationManager.NavigateTo(uriString!.ToString()!, replace: true);

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/ClientPubSubMessages.cs

@@ -8,40 +8,94 @@ public partial class ClientPubSubMessages
     : SharedPubSubMessages
     //#endif
 {
+    /// <summary>
+    /// A publisher that publishes this message wants a snack bar to be shown.
+    /// </summary>
     public const string SHOW_SNACK = nameof(SHOW_SNACK);
+
+    /// <summary>
+    /// A publisher that publishes this message wants a modal to be shown.
+    /// </summary>
     public const string SHOW_MODAL = nameof(SHOW_MODAL);
+
+    /// <summary>
+    /// A publisher that publishes this message wants a modal to be closed.
+    /// </summary>
     public const string CLOSE_MODAL = nameof(CLOSE_MODAL);
 
+    /// <summary>
+    /// This message gets published when the app theme is changed.
+    /// </summary>
     public const string THEME_CHANGED = nameof(THEME_CHANGED);
+
+    /// <summary>
+    /// A publisher that publishes this message wants the navigation panel to be opened.
+    /// </summary>
     public const string OPEN_NAV_PANEL = nameof(OPEN_NAV_PANEL);
+
+    /// <summary>
+    /// A publisher that publishes this message wants the navigation panel to be closed.
+    /// </summary>
     public const string CLOSE_NAV_PANEL = nameof(CLOSE_NAV_PANEL);
+
+    /// <summary>
+    /// When the culture is changed, this message is published.
+    /// </summary>
     public const string CULTURE_CHANGED = nameof(CULTURE_CHANGED);
+
     /// <summary>
     /// <inheritdoc cref="Parameters.IsOnline"/>
     /// </summary>
     public const string IS_ONLINE_CHANGED = nameof(IS_ONLINE_CHANGED);
+
+    /// <summary>
+    /// When the data of the current page is changed, this message is published.
+    /// </summary>
     public const string PAGE_DATA_CHANGED = nameof(PAGE_DATA_CHANGED);
+
+    /// <summary>
+    /// When the route data is updated, this message is published.
+    /// </summary>
     public const string ROUTE_DATA_UPDATED = nameof(ROUTE_DATA_UPDATED);
 
     /// <summary>
     /// Supposed to be called using JavaScript to navigate between pages without reloading the app.
     /// </summary>
     public const string NAVIGATE_TO = nameof(NAVIGATE_TO);
+
+    /// <summary>
+    /// A publisher that publishes this message wants the diagnostic modal to be shown.
+    /// </summary>
     public const string SHOW_DIAGNOSTIC_MODAL = nameof(SHOW_DIAGNOSTIC_MODAL);
 
     //#if (signalR != true)
+    /// <summary>
+    /// When the user profile is updated, this message is published.
+    /// </summary>
     public const string PROFILE_UPDATED = nameof(PROFILE_UPDATED);
     //#endif
 
     //#if(module == "Sales")
+    /// <summary>
+    /// When a user taps on search bar, this message is published to open the AI chat panel with product search prompt.
+    /// </summary>
     public const string SEARCH_PRODUCTS = nameof(SEARCH_PRODUCTS);
     //#endif
 
     //#if(ads == true)
+    /// <summary>
+    /// When a user has trouble with ads, this message is published to open the AI chat panel with ad help prompt.
+    /// </summary>
     public const string AD_HAVE_TROUBLE = nameof(AD_HAVE_TROUBLE);
     //#endif
 
-    public const string SOCIAL_SIGN_IN = nameof(SOCIAL_SIGN_IN);
+    /// <summary>
+    /// When a user completes social sign-in in a separate window, this message is published to notify the app.
+    /// </summary>
+    public const string SOCIAL_SIGN_IN_CALLBACK = nameof(SOCIAL_SIGN_IN_CALLBACK);
 
+    /// <summary>
+    /// A publisher that publishes this message wants to force the app to check for updates and install them.
+    /// </summary>
     public const string FORCE_UPDATE = nameof(FORCE_UPDATE);
 }

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/Contracts/ILocalHttpServer.cs

@@ -1,5 +1,6 @@
-namespace Boilerplate.Client.Core.Services.Contracts;
+namespace Boilerplate.Client.Core.Services.Contracts;
 
+// Checkout Client.web/wwwroot/web-interop-app.html's comments.
 public interface ILocalHttpServer : IAsyncDisposable
 {
     int EnsureStarted();

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/DefaultExternalNavigationService.cs

@@ -36,7 +36,7 @@ public async Task NavigateToAsync(string url)
         else
         {
             pubSubUnsubscribe?.Invoke();
-            pubSubUnsubscribe = pubSubService.Subscribe(ClientPubSubMessages.SOCIAL_SIGN_IN, async _ =>
+            pubSubUnsubscribe = pubSubService.Subscribe(ClientPubSubMessages.SOCIAL_SIGN_IN_CALLBACK, async _ =>
             {
                 if (lastOpenedWindowId != null)
                 {