From 409bdce4d8d839c667867aa6e3cc63e34e41f317 Mon Sep 17 00:00:00 2001
From: Gabriel de Perthuis <g2p.code@gmail.com>
Date: Thu, 21 Sep 2023 15:51:24 +0200
Subject: [PATCH] Better document the interaction of SsrModes with blocking
 resources

Meant to address users making the same mistake as
https://github.com/leptos-rs/leptos/issues/1119
---
 docs/book/src/ssr/23_ssr_modes.md | 23 +++++++++++++++++++++--
 leptos_reactive/src/resource.rs   |  5 +++++
 router/src/render_mode.rs         | 18 +++++++++---------
 3 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/docs/book/src/ssr/23_ssr_modes.md b/docs/book/src/ssr/23_ssr_modes.md
index f49597e7ce..e89db9858c 100644
--- a/docs/book/src/ssr/23_ssr_modes.md
+++ b/docs/book/src/ssr/23_ssr_modes.md
@@ -67,7 +67,7 @@ If you’re using server-side rendering, the synchronous mode is almost never wh
   - Able to show the fallback loading state and dynamically replace it, instead of showing blank sections for un-loaded data.
 - _Cons_: Requires JavaScript to be enabled for suspended fragments to appear in correct order. (This small chunk of JS streamed down in a `<script>` tag alongside the `<template>` tag that contains the rendered `<Suspense/>` fragment, so it does not need to load any additional JS files.)
 
-5. **Partially-blocked streaming**: “Partially-blocked” streaming is useful when you have multiple separate `<Suspense/>` components on the page. If one of them reads from one or more “blocking resources” (see below), the fallback will not be sent; rather, the server will wait until that `<Suspense/>` has resolved and then replace the fallback with the resolved fragment on the server, which means that it is included in the initial HTML response and appears even if JavaScript is disabled or not supported. Other `<Suspense/>` stream in out of order as usual.
+5. **Partially-blocked streaming**: “Partially-blocked” streaming is useful when you have multiple separate `<Suspense/>` components on the page.  It is triggered by setting `ssr=SsrMode::PartiallyBlocked` on a route, and depending on blocking resources within the view.   If one of the `<Suspense/>` components reads from one or more “blocking resources” (see below), the fallback will not be sent; rather, the server will wait until that `<Suspense/>` has resolved and then replace the fallback with the resolved fragment on the server, which means that it is included in the initial HTML response and appears even if JavaScript is disabled or not supported. Other `<Suspense/>` stream in out of order, similar to the `SsrMode::OutOfOrder` default.
 
 This is useful when you have multiple `<Suspense/>` on the page, and one is more important than the other: think of a blog post and comments, or product information and reviews. It is _not_ useful if there’s only one `<Suspense/>`, or if every `<Suspense/>` reads from blocking resources. In those cases it is a slower form of `async` rendering.
 
@@ -134,4 +134,23 @@ pub fn BlogPost() -> impl IntoView {
 }
 ```
 
-The first `<Suspense/>`, with the body of the blog post, will block my HTML stream, because it reads from a blocking resource. The second `<Suspense/>`, with the comments, will not block the stream. Blocking resources gave me exactly the power and granularity I needed to optimize my page for SEO and user experience.
+The first `<Suspense/>`, with the body of the blog post, will block my HTML stream, because it reads from a blocking resource.  Meta tags and other head elements awaiting the blocking resource will be rendered before the stream is sent.
+
+Combined with the following route definition, which uses `SsrMode::PartiallyBlocked`, the blocking resource will be fully rendered on the server side, making it accessible to users who disable WebAssembly or JavaScript.
+
+```rust
+<Routes>
+	// We’ll load the home page with out-of-order streaming and <Suspense/>
+	<Route path="" view=HomePage/>
+
+	// We'll load the posts with async rendering, so they can set
+	// the title and metadata *after* loading the data
+	<Route
+		path="/post/:id"
+		view=Post
+		ssr=SsrMode::PartiallyBlocked
+	/>
+</Routes>
+```
+
+The second `<Suspense/>`, with the comments, will not block the stream. Blocking resources gave me exactly the power and granularity I needed to optimize my page for SEO and user experience.
diff --git a/leptos_reactive/src/resource.rs b/leptos_reactive/src/resource.rs
index eb1c03314b..7a2b894484 100644
--- a/leptos_reactive/src/resource.rs
+++ b/leptos_reactive/src/resource.rs
@@ -143,6 +143,11 @@ where
 ///
 /// **Note**: This is not “blocking” in the sense that it blocks the current thread. Rather,
 /// it is blocking in the sense that it blocks the server from sending a response.
+///
+/// When used with the leptos_router and `SsrMode::PartiallyBlocked`, a
+/// blocking resource will ensure `<Suspense/>` blocks depending on the resource
+/// are fully rendered on the server side, without requiring JavaScript or
+/// WebAssembly on the client.
 #[cfg_attr(
     any(debug_assertions, feature="ssr"),
     instrument(
diff --git a/router/src/render_mode.rs b/router/src/render_mode.rs
index 7c81cc0c9c..59a882673f 100644
--- a/router/src/render_mode.rs
+++ b/router/src/render_mode.rs
@@ -1,27 +1,27 @@
 /// Indicates which rendering mode should be used for this route during server-side rendering.
 ///
-/// Leptos supports four different ways to render HTML that contains `async` data loaded
+/// Leptos supports the following ways of rendering HTML that contains `async` data loaded
 /// under `<Suspense/>`.
-/// 1. **Synchronous**: Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the client, replacing `fallback` once they're loaded.
+/// 1. **Synchronous** (use any mode except `Async`, don't depend on any resource): Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the client (using `create_local_resource`), replacing `fallback` once they're loaded.
 ///     - *Pros*: App shell appears very quickly: great TTFB (time to first byte).
 ///     - *Cons*: Resources load relatively slowly; you need to wait for JS + Wasm to load before even making a request.
-/// 2. **Out-of-order streaming**: Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the **server**, streaming it down to the client as it resolves, and streaming down HTML for `Suspense` nodes.
-///     - *Pros*: Combines the best of **synchronous** and **`async`**, with a very fast shell and resources that begin loading on the server.
+/// 2. **Out-of-order streaming** (`OutOfOrder`, the default): Serve an HTML shell that includes `fallback` for any `Suspense`. Load data on the **server**, streaming it down to the client as it resolves, and streaming down HTML for `Suspense` nodes.
+///     - *Pros*: Combines the best of **synchronous** and `Async`, with a very fast shell and resources that begin loading on the server.
 ///     - *Cons*: Requires JS for suspended fragments to appear in correct order. Weaker meta tag support when it depends on data that's under suspense (has already streamed down `<head>`)
-/// 3. **Partially-blocked out-of-order streaming**: Using `create_blocking_resource` with out-of-order streaming still sends fallbacks and relies on JavaScript to fill them in with the fragments. Partially-blocked streaming does this replacement on the server, making for a slower response but requiring no JavaScript to show blocking resources.
+/// 3. **Partially-blocked out-of-order streaming** (`PartiallyBlocked`): Using `create_blocking_resource` with out-of-order streaming still sends fallbacks and relies on JavaScript to fill them in with the fragments. Partially-blocked streaming does this replacement on the server, making for a slower response but requiring no JavaScript to show blocking resources.
 ///     - *Pros*: Works better if JS is disabled.
 ///     - *Cons*: Slower initial response because of additional string manipulation on server.
-/// 4. **In-order streaming**: Walk through the tree, returning HTML synchronously as in synchronous rendering and out-of-order streaming until you hit a `Suspense`. At that point, wait for all its data to load, then render it, then the rest of the tree.
+/// 4. **In-order streaming** (`InOrder`): Walk through the tree, returning HTML synchronously as in synchronous rendering and out-of-order streaming until you hit a `Suspense`. At that point, wait for all its data to load, then render it, then the rest of the tree.
 ///     - *Pros*: Does not require JS for HTML to appear in correct order.
 ///     - *Cons*: Loads the shell more slowly than out-of-order streaming or synchronous rendering because it needs to pause at every `Suspense`. Cannot begin hydration until the entire page has loaded, so earlier pieces
 ///       of the page will not be interactive until the suspended chunks have loaded.
-/// 5. **`async`**: Load all resources on the server. Wait until all data are loaded, and render HTML in one sweep.
+/// 5. **`Async`**: Load all resources on the server. Wait until all data are loaded, and render HTML in one sweep.
 ///     - *Pros*: Better handling for meta tags (because you know async data even before you render the `<head>`). Faster complete load than **synchronous** because async resources begin loading on server.
 ///     - *Cons*: Slower load time/TTFB: you need to wait for all async resources to load before displaying anything on the client.
 ///
 /// The mode defaults to out-of-order streaming. For a path that includes multiple nested routes, the most
-/// restrictive mode will be used: i.e., if even a single nested route asks for `async` rendering, the whole initial
-/// request will be rendered `async`. (`async` is the most restricted requirement, followed by in-order, out-of-order, and synchronous.)
+/// restrictive mode will be used: i.e., if even a single nested route asks for `Async` rendering, the whole initial
+/// request will be rendered `Async`. (`Async` is the most restricted requirement, followed by `InOrder`, `PartiallyBlocked`, and `OutOfOrder`.)
 #[derive(Default, Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum SsrMode {
     #[default]