Improve bit Boilerplate docs (#11591)

[ysmoradi]

closes #11591

Summary by CodeRabbit

• Documentation

  • Enhanced push notification testing guidance with four app-state scenarios and cross-platform handling notes
  • Added SignalR server-client messaging example for reactive dashboard data updates

• Bug Fixes

  • Corrected social sign-in callback event flow to properly route authentication completion

• Chores

  • Expanded internal event messaging constants for consistent UI and application event handling
  • Updated stream prerendering API usage
  • Added component documentation comments

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

The pull request expands documentation about push notifications and messaging workflows, adds new Pub/Sub message constants for UI and app events, renames the social sign-in callback event from SOCIAL_SIGN_IN to SOCIAL_SIGN_IN_CALLBACK across multiple files, refactors stream prerendering API usage, and adds inline documentation comments.

Changes

Cohort / File(s)	Summary
Documentation & markdown updates .docs/22- Messaging.md, .github/copilot-instructions.md, .github/prompts/getting-started.prompt.md	Expanded push notification documentation with detailed scenarios for different app states (closed/open, foreground/background), added server/client SignalR workflow examples, and updated prompt guidance for testing push notifications.
Pub/Sub message constants src/Client/Boilerplate.Client.Core/Services/ClientPubSubMessages.cs	Added 15 new message constants (SHOW_SNACK, SHOW_MODAL, CLOSE_MODAL, THEME_CHANGED, OPEN_NAV_PANEL, CLOSE_NAV_PANEL, CULTURE_CHANGED, PAGE_DATA_CHANGED, ROUTE_DATA_UPDATED, NAVIGATE_TO, SHOW_DIAGNOSTIC_MODAL, PROFILE_UPDATED, SEARCH_PRODUCTS, AD_HAVE_TROUBLE, FORCE_UPDATE) with XML documentation. Renamed SOCIAL_SIGN_IN to SOCIAL_SIGN_IN_CALLBACK.
Social sign-in callback migration src/Client/Boilerplate.Client.Core/Components/Pages/Identity/SignIn/SignInPanel.razor.cs, src/Client/Boilerplate.Client.Core/Components/Pages/Identity/SignUp/SignUpPage.razor.cs, src/Client/Boilerplate.Client.Core/Services/DefaultExternalNavigationService.cs, src/Client/Boilerplate.Client.Maui/Services/MauiLocalHttpServer.cs, src/Client/Boilerplate.Client.Windows/Services/WindowsLocalHttpServer.cs	Updated PubSub subscriptions and message publishes from SOCIAL_SIGN_IN to SOCIAL_SIGN_IN_CALLBACK in social sign-in callback handlers.
Stream prerendering API refactoring src/Server/Boilerplate.Server.Web/Components/App.razor, src/Server/Boilerplate.Server.Web/Extensions/HttpRequestExtensions.cs	Renamed DisableStreamPrerendering() method to IsStreamPrerenderingSuppressed() in HttpRequestExtensions and updated App.razor usage accordingly.
Component documentation comments src/Client/Boilerplate.Client.Core/Components/Common/Prompt.razor, src/Client/Boilerplate.Client.Core/Components/Layout/AppAiChatPanel.razor.cs	Added Razor/inline comments describing component purpose and streaming behavior.
Service interface & documentation src/Client/Boilerplate.Client.Core/Services/Contracts/ILocalHttpServer.cs, src/Client/Boilerplate.Client.Core/Services/NoopLocalHttpServer.cs	Added comment lines above interface declaration and before namespace.
XML documentation updates src/Shared/Services/AppFeatureRequirement.cs, src/Shared/Services/AuthPolicies.cs	Added XML summary for AppFeatureRequirement record. Updated PRIVILEGED_ACCESS documentation to clarify access token permission details. Changed ELEVATED_ACCESS wording from "account removal" to "account deletion".

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Areas requiring extra attention:

• ClientPubSubMessages.cs: Verify all 15 new constants are intentional and correctly named; ensure no naming conflicts with existing usage patterns elsewhere in the codebase.
• Social sign-in callback migration: Confirm the SOCIAL_SIGN_IN_CALLBACK name change is applied consistently across all five files and that no subscribers still reference the old SOCIAL_SIGN_IN constant.
• Stream prerendering API rename: Check that IsStreamPrerenderingSuppressed() behavior matches the original DisableStreamPrerendering() intent; verify no other call sites depend on the old method name.
• Public API changes: The method rename in HttpRequestExtensions.cs is a breaking change; confirm all existing callers have been updated.

Poem

🐰 New constants hop across the messages,
Social callbacks find their way home,
Stream prerendering speaks its truth,
Push notifications bloom anew,
Our boilerplate grows wise with docs! ✨

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes changes beyond documentation: public API modifications in ClientPubSubMessages (replacing SOCIAL_SIGN_IN with SOCIAL_SIGN_IN_CALLBACK), HttpRequestExtensions method rename, and implementation changes in multiple service files.	Clarify whether API changes (PubSub message constants, HttpRequestExtensions rename) are scope of issue #11591 or should be in a separate PR. Separate documentation-only changes from code refactoring.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Linked Issues check	❓ Inconclusive	The linked issue #11591 provides only a title 'bit Boilerplate docs need improvements' with no detailed objectives or requirements specified, making compliance assessment impossible.	Review the detailed requirements in issue #11591 to ensure all coding-related objectives are met. Verify the changes address the specific documentation improvements requested.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'Improve bit Boilerplate docs' accurately reflects the main focus of the changes, which involve updates to documentation files (.md files), comments, and descriptions across the boilerplate.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between 83cbee2 and 144a948.

📒 Files selected for processing (17)

• src/Templates/Boilerplate/Bit.Boilerplate/.docs/22- Messaging.md (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/.github/copilot-instructions.md (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/.github/prompts/getting-started.prompt.md (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Common/Prompt.razor (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Layout/AppAiChatPanel.razor.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Pages/Identity/SignIn/SignInPanel.razor.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Components/Pages/Identity/SignUp/SignUpPage.razor.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/ClientPubSubMessages.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/Contracts/ILocalHttpServer.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/DefaultExternalNavigationService.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/NoopLocalHttpServer.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Maui/Services/MauiLocalHttpServer.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Windows/Services/WindowsLocalHttpServer.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Server/Boilerplate.Server.Web/Components/App.razor (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Server/Boilerplate.Server.Web/Extensions/HttpRequestExtensions.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Shared/Services/AppFeatureRequirement.cs (1 hunks)
• src/Templates/Boilerplate/Bit.Boilerplate/src/Shared/Services/AuthPolicies.cs (1 hunks)

🧰 Additional context used

🪛 LanguageTool

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

[style] ~555-~555: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e user tapped on the notification. 3. Scenario 3: The app was open when the noti...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

---

[style] ~556-~556: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e user tapped on the notification. 4. Scenario 4: The app was open when the noti...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build and test

🔇 Additional comments (18)

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

3-4: Clear and helpful documentation addition.

The comment accurately describes the component's purpose and is well-placed at the top of the file. This improves discoverability for developers working with this component.

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

161-162: Excellent documentation of the streaming logic.

The inline comments clearly explain the dual purpose of the subsequent code: streaming user input to the server and maintaining the chat until cancellation. This significantly improves readability for developers working with this SignalR streaming pattern.

src/Templates/Boilerplate/Bit.Boilerplate/.github/copilot-instructions.md (1)

131-131: Consistent emphasis improves documentation clarity.

The bolding of "partial static classes and extensions methods" follows the established pattern in this document for emphasizing key conventions and attribute names (e.g., **Bit.BlazorUI**, **AutoInject**, **WrapHandled**). This formatting change enhances readability and helps developers quickly identify the Mapperly convention requirement.

src/Templates/Boilerplate/Bit.Boilerplate/src/Shared/Services/AppFeatureRequirement.cs (1)

5-7: No issues found with the XML documentation reference.

The AppFeatures type exists as a public class in the same service directory, making the <inheritdoc cref="AppFeatures"/> reference valid and resolvable. The documentation is correctly formatted.

src/Templates/Boilerplate/Bit.Boilerplate/src/Shared/Services/AuthPolicies.cs (1)

23-23: Good terminology improvement.

Changing "account removal" to "account deletion" improves clarity and consistency.

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

3-3: LGTM! Helpful documentation reference added.

The comment directs developers to additional documentation in web-interop-app.html, which improves discoverability of related implementation details.

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/NoopLocalHttpServer.cs (1)

3-3: LGTM! Consistent documentation pattern.

The same helpful reference comment is added here as in ILocalHttpServer.cs, maintaining consistency across the codebase.

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Windows/Services/WindowsLocalHttpServer.cs (1)

61-61: LGTM! Consistent PubSub topic rename.

The social sign-in callback now publishes to SOCIAL_SIGN_IN_CALLBACK instead of SOCIAL_SIGN_IN, aligning with the updated messaging contract across all platforms.

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

93-93: LGTM! Subscriber updated to match renamed event.

The subscription correctly uses SOCIAL_SIGN_IN_CALLBACK, ensuring the social sign-up flow receives callbacks on the updated topic.

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

1086-1091: LGTM! Comprehensive push notification testing guidance.

The four scenarios provide a clear testing matrix covering all combinations of app states when notifications are sent and tapped. This documentation helps developers ensure robust push notification handling across all platforms.

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Maui/Services/MauiLocalHttpServer.cs (1)

76-76: LGTM! Consistent cross-platform PubSub update.

The Maui implementation now publishes to SOCIAL_SIGN_IN_CALLBACK, maintaining consistency with the Windows platform and subscriber expectations.

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

214-214: LGTM! Sign-in flow aligned with updated messaging.

The subscription to SOCIAL_SIGN_IN_CALLBACK ensures the sign-in flow receives social authentication callbacks on the correct topic.

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/DefaultExternalNavigationService.cs (1)

39-39: LGTM! External navigation service updated consistently.

The subscription to SOCIAL_SIGN_IN_CALLBACK ensures the opened social sign-in window is properly closed after the callback completes, maintaining the intended user experience on the web platform.

src/Templates/Boilerplate/Bit.Boilerplate/.docs/22- Messaging.md (2)

549-560: Excellent addition to push notification testing guidance!

This section provides clear, actionable guidance for testing push notifications across four distinct app states. The enumeration of scenarios (app closed/open when notification sent, and closed/open when user taps) covers all edge cases developers need to verify.

Note: The static analysis tool flagged repetitive sentence structure starting with "Scenario," but this is appropriate and expected for a numbered list format.

---

562-596: Great end-to-end example of real-time data synchronization!

The Dashboard Data Changed example effectively demonstrates how server-side CRUD operations trigger real-time updates to all authenticated clients through SignalR and PubSubService, showcasing the complete messaging workflow in a practical scenario.

src/Templates/Boilerplate/Bit.Boilerplate/src/Client/Boilerplate.Client.Core/Services/ClientPubSubMessages.cs (2)

11-100: Excellent addition of XML documentation comments!

The comprehensive XML documentation significantly improves developer experience by providing clear context for each pub/sub message constant. The comments are concise, consistent, and will enhance IntelliSense tooltips throughout the codebase.

---

92-95: Improved naming for social sign-in callback message!

The rename from SOCIAL_SIGN_IN to SOCIAL_SIGN_IN_CALLBACK is more descriptive and clarifies that this message specifically handles the callback event when social sign-in completes in a separate window. The XML documentation reinforces this intent.

src/Templates/Boilerplate/Bit.Boilerplate/src/Server/Boilerplate.Server.Web/Components/App.razor (1)

73-73: LGTM! Updated usage aligns with the renamed API.

The call to IsStreamPrerenderingSuppressed() correctly reflects the renamed extension method and maintains the same conditional logic for determining which rendering container to use.