feat(templates): improve bit Boilerplate docs #11591 (#11592)

Author: ysmoradi

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

@@ -546,7 +546,27 @@ private async Task ShowNotification()
 
 ---
 
-## 7. Dashboard Data Changed Example
+## 7. Testing Push Notifications - Understanding the Four Scenarios
+
+When testing push notifications, it's critical to understand that there are **four distinct scenarios** based on the app state when the notification is sent and when the user taps on it. The Boilerplate project handles all four scenarios across all platforms.
+
+✅ **Scenario 1**: Close the app completely → Send push notification → Tap the notification → Verify the app opens to the correct page
+
+✅ **Scenario 2**: Close the app → Send push notification → Open the app manually (without tapping notification) → Now tap the notification → Verify navigation works
+
+✅ **Scenario 3**: Keep the app open → Send push notification → Close the app → Tap the notification → Verify the app opens to the correct page
+
+✅ **Scenario 4**: Keep the app open → Send push notification → Tap the notification immediately → Verify navigation works without restarting the app
+
+### Key Takeaways
+
+- The codebase includes specialized handling for all four push notification scenarios
+- Different entry points are used depending on the app state (e.g., `OnCreate` vs `OnNewIntent` on Android)
+- Service workers on the web platform handle scenario detection automatically using `clients.matchAll()`
+
+---
+
+## 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)
                 {