Reconnect UI component (#34842)

Author: guardrex

aspnetcore/blazor/fundamentals/signalr.md

@@ -519,7 +519,78 @@ If reconnection fails, the user is instructed to retry or reload the page:
 
 If reconnection succeeds, user state is often lost. Custom code can be added to any component to save and reload user state across connection failures. For more information, see <xref:blazor/state-management>.
 
-:::moniker range=">= aspnetcore-8.0"
+:::moniker range=">= aspnetcore-10.0"
+
+To create UI elements that track reconnection state, the following table describes:
+
+* A set of `components-reconnect-*` CSS classes (**Css class** column) that are set or unset by Blazor on an element with an `id` of `components-reconnect-modal`.
+* A `components-reconnect-state-changed` event (**Event** column) that indicates a reconnection status change.
+
+| CSS class | Event | Indicates&hellip; |
+| --- | --- | --- |
+| `components-reconnect-show` | `show` | A lost connection. The client is attempting to reconnect. The reconnection modal is shown. |
+| `components-reconnect-hide` | `hide` | An active connection is re-established to the server. The reconnection model is closed. |
+| `components-reconnect-retrying` | `retrying` | The client is attempting to reconnect. |
+| `components-reconnect-failed` | `failed` | Reconnection failed, probably due to a network failure. |
+| `components-reconnect-rejected` | `rejected` | Reconnection rejected. |
+
+When the reconnection state change in `components-reconnect-state-changed` is `failed`, call `Blazor.reconnect()` in JavaScript to attempt reconnection.
+
+When the reconnection state change is `rejected`, the server was reached but refused the connection, and the user's state on the server is lost. To reload the app, call `location.reload()` in JavaScript. This connection state may result when:
+
+* A crash in the server-side circuit occurs.
+* The client is disconnected long enough for the server to drop the user's state. Instances of the user's components are disposed.
+* The server is restarted, or the app's worker process is recycled.
+
+The developer adds an event listener on the reconnect modal element to monitor and react to reconnection state changes, as seen in the following example:
+
+```javascript
+const reconnectModal = document.getElementById("components-reconnect-modal");
+reconnectModal.addEventListener("components-reconnect-state-changed", 
+  handleReconnectStateChanged);
+
+function handleReconnectStateChanged(event) {
+  if (event.detail.state === "show") {
+    reconnectModal.showModal();
+  } else if (event.detail.state === "hide") {
+    reconnectModal.close();
+  } else if (event.detail.state === "failed") {
+    Blazor.reconnect();
+  } else if (event.detail.state === "rejected") {
+    location.reload();
+  }
+}
+```
+
+An element with an `id` of `components-reconnect-max-retries` displays the maximum number of reconnect retries:
+
+```html
+<span id="components-reconnect-max-retries"></span>
+```
+
+An element with an `id` of `components-reconnect-current-attempt` displays the current reconnect attempt:
+
+```html
+<span id="components-reconnect-current-attempt"></span>
+```
+
+An element with an `id` of `components-seconds-to-next-attempt` displays the number of seconds to the next reconnection attempt:
+
+```html
+<span id="components-seconds-to-next-attempt"></span>
+```
+
+The Blazor Web App project template includes a `ReconnectModal` component (`Components/Layout/ReconnectModal.razor`) with collocated stylesheet and JavaScript files (`ReconnectModal.razor.css`, `ReconnectModal.razor.js`) that can be customized as needed. These files can be examined in the ASP.NET Core reference source or by inspecting an app created from the Blazor Web App project template. The component is added to the project when the project is created in Visual Studio with **Interactive render mode** set to **Server** or **Auto** or created with the .NET CLI with the option `--interactivity server` (default) or `--interactivity auto`.
+
+* [`ReconnectModal` component](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor)
+* [Stylesheet file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor.css)
+* [JavaScript file](https://github.com/dotnet/aspnetcore/blob/main/src/ProjectTemplates/Web.ProjectTemplates/content/BlazorWeb-CSharp/BlazorWeb-CSharp/Components/Layout/ReconnectModal.razor.js)
+
+[!INCLUDE[](~/includes/aspnetcore-repo-ref-source-links.md)]
+
+:::moniker-end
+
+:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"
 
 To customize the UI, define a single element with an `id` of `components-reconnect-modal` in the `<body>` element content. The following example places the element in the `App` component.
 
@@ -551,6 +622,8 @@ To customize the UI, define a single element with an `id` of `components-reconne
 
 :::moniker-end
 
+:::moniker range="< aspnetcore-10.0"
+
 ```cshtml
 <div id="components-reconnect-modal">
     Connection lost.<br>Attempting to reconnect...
@@ -562,7 +635,9 @@ To customize the UI, define a single element with an `id` of `components-reconne
 
 Add the following CSS styles to the site's stylesheet.
 
-:::moniker range=">= aspnetcore-8.0"
+:::moniker-end
+
+:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"
 
 `wwwroot/app.css`:
 
@@ -574,6 +649,8 @@ Add the following CSS styles to the site's stylesheet.
 
 :::moniker-end
 
+:::moniker range="< aspnetcore-10.0"
+
 ```css
 #components-reconnect-modal {
     display: none;
@@ -604,13 +681,15 @@ The following table describes the CSS classes applied to the `components-reconne
 | `components-reconnect-failed`   | Reconnection failed, probably due to a network failure. To attempt reconnection, call `window.Blazor.reconnect()` in JavaScript. |
 | `components-reconnect-rejected` | Reconnection rejected. The server was reached but refused the connection, and the user's state on the server is lost. To reload the app, call `location.reload()` in JavaScript. This connection state may result when:<ul><li>A crash in the server-side circuit occurs.</li><li>The client is disconnected long enough for the server to drop the user's state. Instances of the user's components are disposed.</li><li>The server is restarted, or the app's worker process is recycled.</li></ul> |
 
-:::moniker range=">= aspnetcore-5.0"
+:::moniker-end
+
+:::moniker range=">= aspnetcore-5.0 < aspnetcore-10.0"
 
 Customize the delay before the reconnection UI appears by setting the `transition-delay` property in the site's CSS for the modal element. The following example sets the transition delay from 500 ms (default) to 1,000 ms (1 second).
 
 :::moniker-end
 
-:::moniker range=">= aspnetcore-8.0"
+:::moniker range=">= aspnetcore-8.0 < aspnetcore-10.0"
 
 `wwwroot/app.css`:
 
@@ -622,7 +701,7 @@ Customize the delay before the reconnection UI appears by setting the `transitio
 
 :::moniker-end
 
-:::moniker range=">= aspnetcore-5.0"
+:::moniker range=">= aspnetcore-5.0 < aspnetcore-10.0"
 
 ```css
 #components-reconnect-modal {

aspnetcore/release-notes/aspnetcore-10/includes/blazor.md

@@ -36,4 +36,15 @@ The [`[Route]` attribute](xref:Microsoft.AspNetCore.Components.RouteAttribute) n
 
 Previously, <xref:Microsoft.AspNetCore.Components.NavigationManager.NavigateTo%2A?displayProperty=nameWithType> scrolled to the top of the page for same-page navigations. This behavior has been changed in .NET 10 so that the browser no longer scrolls to the top of the page when navigating to the same page. This means the viewport is no longer reset when making updates to the address for the current page, such as changing the query string or fragment.
 
+### Reconnection UI component added to the Blazor Web App project template
+
+The Blazor Web App project template now includes a `ReconnectModal` component, including collocated stylesheet and JavaScript files, for improved developer control over the reconnection UI when the client loses the WebSocket connection to the server. The component doesn't insert styles programmatically, so it doesn't violate stricter Content Security Policy (CSP) settings for the `style-src` policy. In prior releases, the default reconnection UI was created by the framework in a way that could cause CSP violations. Note that the default reconnection UI is still used as fallback when the app doesn't define the reconnection UI, such as by using the project template's `ReconnectModal` component or a similar custom component.
+
+New reconnection UI features:
+
+* Apart from indicating the reconnection state by setting a specific CSS class on the reconnection UI element, the new `components-reconnect-state-changed` event is dispatched for reconnection state changes.
+* Code can better differentiate the stages of the reconnection process with the new reconnection state "`retrying`," indicated by both the CSS class and the new event.
+
+For more information, see <xref:blazor/fundamentals/signalr?view=aspnetcore-10.0#reflect-the-server-side-connection-state-in-the-ui>.
+
 -->