[css-view-transitions-2] Add example and note for render-blocking (w3c#10170)

noamr · vmpstr · web-flow · commit 38044b3a5b54 · 2024-04-08T21:18:28.000+01:00
* [css-view-transitions-2] Add example and note for render-blocking

* Update css-view-transitions-2/Overview.bs

Co-authored-by: vmpstr &lt;vmpstr@chromium.org&gt;

---------

Co-authored-by: vmpstr &lt;vmpstr@chromium.org&gt;
diff --git a/css-view-transitions-2/Overview.bs b/css-view-transitions-2/Overview.bs
@@ -139,13 +139,46 @@ See the <a href="#lifecycle">lifecycle</a> section for more details.
 
 ### Waiting for the new state to stabilize ### {#waiting-for-stable-state}
 In same-document view transitions, the author can indicate when the new state of the transition is in a stable state by using the callback passed to {{Document/startViewTransition}}.
-Since cross-document view transitions are declarative, there is no such explicit promise. Instead, the user agent relies on the [=render-blocking mechanism=] to decide when the stable state is ready.
+Since cross-document view transitions are declarative, there is no such explicit promise. Instead, the user agent relies on the [=render-blocking mechanism=] to decide when the document has reached a stable state.
 In this way, the author can use the the <code data-x="">blocking</code> attribute, to delay the transition until:
 	* All expected scripts are executed, by using the script's {{HTMLScriptElement/blocking}} attribute on required scripts.
 	* All expected styles are executed, by using the style or link's {{HTMLStyleElement/blocking}} attribute on required styles.
 	* All expected HTML elements are seen by the parser, using an <{link/rel/expect}> {{HTMLLinkElement}} element.
 
+Note: overusing the render-blocking mechanism could make it so that the old state remains frozen for a long time, resulting in a jarring user experience.
+To avoid this, it's advised to ensure that the render-blocking elements are available in a timely manner.
+
 <div class="example">
+
+In this example, the last frame of the old document will be shown, and the animation will be delayed, until all the following conditions are met:
+- `style.css` is applied, to ensure the new state has the correct styles
+- `fixup.js` is run, to ensure the presentation is up to date with script-based fixups.
+- The `main-article` section is seen and parsed, to ensure enough of the content is loaded before allowing the transition to proceed.
+
+```html
+<!DOCTYPE html>
+<html>
+	<head>
+		< !-- This will be render-blocking by default -->
+		<link rel="stylesheet" href="style.css">
+
+		< !-- Since this script fixes up the layout, marking it as render blocking will
+			  ensure it's run before the view transition is activated -->
+		<script async href="fixup.js" blocking="render"></script>
+
+		< !-- Wait until the main-article element is seen and fully parsed before
+			  activating the transition -->
+		<link rel="expect" href="#main-article" blocking="render">
+	</head>
+	<body>
+		<header>...</header>
+		<main>
+			<article id="main-article">...</article>
+		</main>
+		<article id="secondary-article">...</article>
+	</body>
+</html>
+```
 </div>
 
 ### Customization ### {#customizing-cross-document-view-transitions}
