[css-view-transitions-2] Add example and note for render-blocking (#1…

…0170) * [css-view-transitions-2] Add example and note for render-blocking * Update css-view-transitions-2/Overview.bs Co-authored-by: vmpstr <[email protected]> --------- Co-authored-by: vmpstr <[email protected]>
w3c · Apr 8, 2024 · 38044b3 · 38044b3
1 parent f9c1622
commit 38044b3
Showing 1 changed file with 34 additions and 1 deletion.
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}