@ebay/skin 18.1.0 → 18.2.0

package/src/routes/skeleton-examples/examples/out-of-order/example-3/+page.component-browser.js

@@ -0,0 +1,154 @@
+window.addEventListener("load", () => {
+    const skeletonDelay = 250;
+    const navDelay = 500;
+    const heroDelay = 500;
+    const featured1Delay = 600;
+    const featured2Delay = 700;
+    const articleDelay = 3000;
+    const asideDelay1 = 750;
+    const asideDelay2 = 500;
+    const footerDelay = 500;
+
+    setTimeout(() => {
+        document.querySelector(".page-grid").innerHTML += `
+      <nav>
+        <div class="demo-skeleton"></div>
+      </nav>
+      <article id="hero">
+        <div class="demo-skeleton"></div>
+      </article>
+      <article id="featured-1" class="featured nested-grid-container">
+          <div class="demo-skeleton"></div>
+      </article>
+      <article id="featured-2" class="featured nested-grid-container">
+          <div class="demo-skeleton"></div>
+      </article>
+      <main>
+        <div class="demo-skeleton"></div>
+      </main>
+      <aside>
+        <section id="section-1">
+          <div class="demo-skeleton"></div>
+        </section>
+        <section id="section-2">
+          <div class="demo-skeleton"></div>
+        </section>
+      </aside>
+    `;
+    }, skeletonDelay);
+
+    setTimeout(() => {
+        document.querySelector("nav").innerHTML = `
+      <ul>
+        <li><a href="#">World</a>
+        <li><a href="#">U.S.</a>
+        <li><a href="#">Technology</a>
+        <li><a href="#">Design</a>
+        <li><a href="#">Culture</a>
+        <li><a href="#">Business</a>
+        <li><a href="#">Politics</a>
+        <li><a href="#">Opinion</a>
+        <li><a href="#">Science</a>
+        <li><a href="#">Health</a>
+        <li><a href="#">Style</a>
+        <li><a href="#">Travel</a>
+      </ul>
+    `;
+    }, navDelay);
+
+    setTimeout(() => {
+        document.querySelector("#hero").innerHTML = `
+      <h2>Title of a longer featured blog post</h2>
+      <p>Multiple lines of text that form the lede, informing new readers quickly and efficiently about what's most
+        interesting in this post's contents.</p>
+      <p><a>Continue reading...</a></p>
+    `;
+    }, heroDelay);
+
+    setTimeout(() => {
+        document.querySelector("#featured-1").innerHTML = `
+      <div class="page-grid">
+        <div class="featured__article">
+          <h2>Featured Post 1</h2>
+          <p>This is a wider card with supporting text below as a natural lead-in to additional content.</p>
+        </div>
+        <div class="featured__thumbnail">
+          Thumbnail
+        </div>
+      </div>;
+    `;
+    }, featured1Delay);
+
+    setTimeout(() => {
+        document.querySelector("#featured-2").innerHTML = `
+      <div class="page-grid">
+        <div class="featured__article">
+          <h2>Featured Post 2</h2>
+          <p>This is a wider card with supporting text below as a natural lead-in to additional content.</p>
+        </div>
+        <div class="featured__thumbnail">
+          Thumbnail
+        </div>
+      </div>;
+    `;
+    }, featured2Delay);
+
+    setTimeout(() => {
+        document.querySelector("main").innerHTML = `
+      <article>
+        <h1>From the Firehose</h1>
+        <h2>Sample blog post</h2>
+        <p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean eu leo quam.
+          Pellentesque ornare sem lacinia quam venenatis vestibulum. Sed posuere consectetur est at lobortis. Cras
+          mattis consectetur purus sit amet fermentum.</p>
+        <p>Curabitur blandit tempus porttitor. Nullam quis risus eget urna mollis ornare vel eu leo. Nullam id dolor
+          id nibh ultricies vehicula ut id elit.
+          Etiam porta sem malesuada magna mollis euismod. Cras mattis consectetur purus sit amet fermentum. Aenean
+          lacinia bibendum nulla sed consectetur.</p>
+        <h3>Heading</h3>
+        <p>Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Duis mollis, est non commodo luctus,
+          nisi erat porttitor ligula, eget lacinia odio sem nec elit. Morbi leo risus, porta ac consectetur ac,
+          vestibulum at eros.</p>
+        <h4>Sub-heading</h4>
+        <p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>
+        <pre><code>Example code block</code></pre>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Etiam porta sem malesuada magna mollis euismod. Fusce
+          dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa.</p>
+        <h4>Sub-heading</h4>
+        <p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean lacinia
+          bibendum nulla sed consectetur. Etiam porta sem malesuada magna mollis euismod. Fusce dapibus, tellus ac
+          cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et.
+          Donec id elit non mi porta gravida at eget metus.
+          Nulla vitae elit libero, a pharetra augue.
+          Donec ullamcorper nulla non metus auctor fringilla. Nulla vitae elit libero, a pharetra augue.</p>
+        <p>Vestibulum id ligula porta felis euismod semper.
+          Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.
+          Maecenas sed diam eget risus varius blandit sit amet non magna.
+          Cras mattis consectetur purus sit amet fermentum. Sed posuere consectetur est at lobortis.</p>
+      </article>
+      `;
+    }, articleDelay);
+
+    setTimeout(() => {
+        document.querySelector("#section-1").innerHTML = `
+      <h2>About</h2>
+      <p>Etiam porta sem malesuada magna mollis euismod. Cras mattis consectetur purus sit amet fermentum. Aenean lacinia bibendum nulla sed consectetur.</p>
+    `;
+    }, asideDelay1);
+
+    setTimeout(() => {
+        document.querySelector("#section-2").innerHTML = `
+      <h2>Archives</h2>
+      <p>Etiam porta sem malesuada magna mollis euismod. Cras mattis consectetur purus sit amet fermentum. Aenean lacinia bibendum nulla sed consectetur.</p>
+    `;
+    }, asideDelay2);
+
+    setTimeout(() => {
+        document.body.innerHTML += `
+      <footer>This pen is a "stretchy" CSS Grid recreation of the <a href="https://getbootstrap.com/docs/4.0/examples/blog/">Bootstrap Blog Example</a>.</footer>
+    `;
+    }, footerDelay);
+});
+
+export default {};

package/src/routes/skeleton-examples/examples/out-of-order/example-3/+page.marko

@@ -0,0 +1,3 @@
+<div class="page-grid-container">
+  <div class="page-grid"></div>
+</div>

package/src/routes/skeleton-examples/examples/out-of-order/example-3/+page.style.css

@@ -0,0 +1,27 @@
+aside,
+main,
+.page-grid {
+    outline: 0;
+}
+.demo-skeleton:empty {
+    background: var(--color-loading-fill);
+    border-radius: 8px;
+    height: 150px;
+}
+nav .demo-skeleton:empty {
+    height: 50px;
+}
+article .demo-skeleton:empty {
+    height: 200px;
+}
+#hero .demo-skeleton:empty {
+    background-color: #343a40;
+    height: 150px;
+}
+main .demo-skeleton:empty {
+    height: 800px;
+}
+aside .demo-skeleton:empty {
+    height: 400px;
+    margin-bottom: 16px;
+}

package/src/routes/skeleton-examples/examples/out-of-order/example-4/+meta.json

@@ -0,0 +1,3 @@
+{
+    "title": "Out-of-Order Streaming - Out-of-Order Placeholders Only"
+}

package/src/routes/skeleton-examples/examples/out-of-order/example-4/+page.component-browser.js

@@ -0,0 +1,140 @@
+window.addEventListener("load", () => {
+    const navDelay = 200;
+    const heroDelay = 250;
+    const skeletonDelay = 250;
+    const articleDelay = 3000;
+    const asideDelay1 = 1000;
+    const asideDelay2 = 1500;
+    const footerDelay = 1750;
+
+    setTimeout(() => {
+        document.querySelector(".page-grid").innerHTML += `
+      <nav>
+        <ul>
+          <li><a href="#">World</a>
+          <li><a href="#">U.S.</a>
+          <li><a href="#">Technology</a>
+          <li><a href="#">Design</a>
+          <li><a href="#">Culture</a>
+          <li><a href="#">Business</a>
+          <li><a href="#">Politics</a>
+          <li><a href="#">Opinion</a>
+          <li><a href="#">Science</a>
+          <li><a href="#">Health</a>
+          <li><a href="#">Style</a>
+          <li><a href="#">Travel</a>
+        </ul>
+      </nav>
+    `;
+    }, navDelay);
+
+    setTimeout(() => {
+        document.querySelector(".page-grid").innerHTML += `
+      <article id="hero">
+        <h2>Title of a longer featured blog post</h2>
+        <p>Multiple lines of text that form the lede, informing new readers quickly and efficiently about what's most
+          interesting in this post's contents.</p>
+        <p><a>Continue reading...</a></p>
+      </article>
+      <article id="featured-1" class="featured nested-grid-container">
+        <div class="page-grid">
+          <div class="featured__article">
+            <h2>Featured Post 1</h2>
+            <p>This is a wider card with supporting text below as a natural lead-in to additional content.</p>
+          </div>
+          <div class="featured__thumbnail">
+            Thumbnail
+          </div>
+        </div>
+      </article>
+      <article id="featured-2" class="featured nested-grid-container">
+        <div class="page-grid">
+          <div class="featured__article">
+            <h2>Featured Post 2</h2>
+            <p>This is a wider card with supporting text below as a natural lead-in to additional content.</p>
+          </div>
+          <div class="featured__thumbnail">
+            Thumbnail
+          </div>
+        </div>
+      </article>
+    `;
+    }, heroDelay);
+
+    setTimeout(() => {
+        document.querySelector(".page-grid").innerHTML += `
+      <main>
+        <h1>From the Firehose</h1>
+        <div class="demo-skeleton"></div>
+      </main>
+      <aside>
+        <section id="section-1">
+          <div class="demo-skeleton"></div>
+        </section>
+        <section id="section-2">
+          <div class="demo-skeleton"></div>
+        </section>
+      </aside>
+    `;
+    }, skeletonDelay);
+
+    setTimeout(() => {
+        document.querySelector("main .demo-skeleton").hidden = true;
+
+        document.querySelector("main").innerHTML += `
+      <article>
+        <h2>Sample blog post</h2>
+        <p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean eu leo quam.
+          Pellentesque ornare sem lacinia quam venenatis vestibulum. Sed posuere consectetur est at lobortis. Cras
+          mattis consectetur purus sit amet fermentum.</p>
+        <p>Curabitur blandit tempus porttitor. Nullam quis risus eget urna mollis ornare vel eu leo. Nullam id dolor
+          id nibh ultricies vehicula ut id elit.
+          Etiam porta sem malesuada magna mollis euismod. Cras mattis consectetur purus sit amet fermentum. Aenean
+          lacinia bibendum nulla sed consectetur.</p>
+        <h3>Heading</h3>
+        <p>Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Duis mollis, est non commodo luctus,
+          nisi erat porttitor ligula, eget lacinia odio sem nec elit. Morbi leo risus, porta ac consectetur ac,
+          vestibulum at eros.</p>
+        <h4>Sub-heading</h4>
+        <p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>
+        <pre><code>Example code block</code></pre>
+        <p>Aenean lacinia bibendum nulla sed consectetur. Etiam porta sem malesuada magna mollis euismod. Fusce
+          dapibus, tellus ac cursus commodo, tortor mauris condimentum nibh, ut fermentum massa.</p>
+        <h4>Sub-heading</h4>
+        <p>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aenean lacinia
+          bibendum nulla sed consectetur. Etiam porta sem malesuada magna mollis euismod. Fusce dapibus, tellus ac
+          cursus commodo, tortor mauris condimentum nibh, ut fermentum massa justo sit amet risus.</p>
+        <p>Praesent commodo cursus magna, vel scelerisque nisl consectetur et.
+          Donec id elit non mi porta gravida at eget metus.
+          Nulla vitae elit libero, a pharetra augue.
+          Donec ullamcorper nulla non metus auctor fringilla. Nulla vitae elit libero, a pharetra augue.</p>
+        <p>Vestibulum id ligula porta felis euismod semper.
+          Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.
+          Maecenas sed diam eget risus varius blandit sit amet non magna.
+          Cras mattis consectetur purus sit amet fermentum. Sed posuere consectetur est at lobortis.</p>
+      </article>
+      `;
+    }, articleDelay);
+
+    setTimeout(() => {
+        document.querySelector("#section-1").innerHTML = `
+      <h2>About</h2>
+      <p>Etiam porta sem malesuada magna mollis euismod. Cras mattis consectetur purus sit amet fermentum. Aenean lacinia bibendum nulla sed consectetur.</p>
+    `;
+    }, asideDelay1);
+
+    setTimeout(() => {
+        document.querySelector("#section-2").innerHTML = `
+      <h2>Archives</h2>
+      <p>Etiam porta sem malesuada magna mollis euismod. Cras mattis consectetur purus sit amet fermentum. Aenean lacinia bibendum nulla sed consectetur.</p>
+    `;
+    }, asideDelay2);
+
+    setTimeout(() => {
+        document.body.innerHTML += `
+      <footer>This pen is a "stretchy" CSS Grid recreation of the <a href="https://getbootstrap.com/docs/4.0/examples/blog/">Bootstrap Blog Example</a>.</footer>
+    `;
+    }, footerDelay);
+});
+
+export default {};

package/src/routes/skeleton-examples/examples/out-of-order/example-4/+page.marko

@@ -0,0 +1,3 @@
+<div class="page-grid-container">
+  <div class="page-grid"></div>
+</div>

package/src/routes/skeleton-examples/examples/out-of-order/example-4/+page.style.css

@@ -0,0 +1,14 @@
+aside,
+main,
+.page-grid {
+    outline: 0;
+}
+.demo-skeleton:empty {
+    background: var(--color-loading-fill);
+    border-radius: 8px;
+    height: 600px;
+}
+aside .demo-skeleton:empty {
+    height: 200px;
+    margin-bottom: 16px;
+}

package/src/routes/skeleton-examples/skeleton/+layout.component-browser.js

@@ -0,0 +1,4 @@
+import "prismjs";
+import "prismjs/themes/prism-tomorrow.css";
+
+export default {};

package/src/routes/skeleton-examples/skeleton/+layout.marko

@@ -0,0 +1,58 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <title>${$global.meta.title}</title>
+        <meta name="viewport" content="width=device-width, initial-scale=1"/>
+        <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+    <style>
+        iframe {
+            border: 1px solid #000;
+            width: 320px;
+            height: 480px;
+            min-height: 480px;
+            resize: both;
+            overflow: auto;
+        }
+
+        .template--item {
+            display: inline-block;
+            margin-right: 20px;
+        }
+
+        .template--item_head {
+            display: flex;
+            align-items: baseline;
+        }
+        .template--item_head_actions {
+            margin-left: auto;
+        }
+    </style>
+
+    </head>
+    <body>
+        <header>
+            <div class="page-grid-container">
+                <div class="page-grid">
+                    <div class="app-bar">
+                        <h1 class="app-bar__title">${$global.meta.title}</h1>
+                        <ul class="app-bar__links">
+                            <li><a href="../">< Back to Skin Site</a></li>
+                        </ul>
+                    </div>
+                </div>
+            </div>
+        </header>
+        <div class="page-grid-container">
+            <div class="page-grid">
+                <div class="content">
+
+        <${input.renderBody}/>
+                </div>
+                <footer>
+                    <hr />
+                        <p>Copyright &copy; ${(new Date()).getFullYear()} eBay, Inc. All rights reserved.</p>
+                </footer>
+            </div>
+        </div>
+    </body>
+</html>

package/src/routes/skeleton-examples/skeleton/+page.marko

@@ -0,0 +1,176 @@
+
+<p>This page details <a href="#techniques">implementation techniques</a> and <a href="#scenarios">common loading scenarios</a> for eBay Skin's <a href="../index.html#skeleton">skeleton</a> module.</p>
+<p><strong>NOTE:</strong> This page demonstrates both good and bad uses of skeletons; please be sure to read and understand carefully to avoid replicating an anti-pattern!</p>
+
+<hr />
+
+<h2 id="techniques">Techniques</h2>
+<p>Skeletons can be used as placeholders for content (i.e. reserving physical space in the page) using either a pure CSS approach, or a DOM manipulation approach with JavaScript.</p>
+
+<h3 id="techniques-css">Technique 1: Pure CSS</h3>
+<p>This technique leverages the CSS <span class="highlight">:empty</span> pseudo-class, as documented in the article, <a href="https://dev.to/tigt/skeleton-screens-but-fast-48f1">"Skeleton screens, but fast"</a> by Taylor Hunt. This approach is highly performant, especially on devices with limited CPU resources.</p>
+<p>If an element is empty, then its <span class="highlight">:empty</span> selector matches, and the associated styles (i.e. the skeleton graphics) are applied. When the content is rendered, <span class="highlight">:empty</span> no longer matches, and the styles (our skeleton graphics) are removed. Marvellous!</p>
+<p>The HTML would look like this:</p>
+<highlight-code type="html" >
+<div class="search-results-skeleton">
+<!-- this element will match :empty until content is inserted -->
+</div>
+</highlight-code>
+
+<p>The CSS selector like so:</p>
+
+<highlight-code type="css" code=`
+.search-results-skeleton:empty {
+/* app developer must write CSS to create skeleton graphics */
+}
+`></highlight-code>
+
+<p><strong>NOTE:</strong> The <span class="highlight">:empty</span> pseudo-class considers elements with whitespace as not empty!</p>
+<p>The downside is that our <a href="../index.html#skeleton">skeleton classes</a> cannot be leveraged (in theory, LESS mixins could be provided) and <em>composite</em> skeletons (e.g. items tiles) may require some non-trivial use of CSS linear gradients for certain skeletons.</p>
+
+<hr />
+
+<h3 id="techniques-javascript">Technique 2: JavaScript</h3>
+<p>With JavaScript, we gain more flexibility and control over when and how the skeleton placeholder is replaced with the actual content. We can either remove the skeleton node from the DOM, as shown below.</p>
+
+<highlight-code type="html" >
+<!-- Before -->
+<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
+<div class="skeleton__button"></div>
+</div>
+
+<!-- After -->
+<div>
+<p>content</p>
+</div>
+</highlight-code>
+
+<p>Or we can simply hide the skeleton, using the <span class="highlight">hidden</span> property.</p>
+
+<highlight-code type="html" >
+<!-- Before -->
+<div class="skeleton" role="img" aria-label="loading" style="width: 200px;">
+<div class="skeleton__button"></div>
+</div>
+
+<!-- After -->
+<div class="skeleton" role="img" aria-label="loading" style="width: 200px;" hidden>
+<div class="skeleton__button"></div>
+</div>
+<div>
+<p>content</p>
+</div>
+</highlight-code>
+
+<p>Notice that JavaScript also gives us the ability to add and remove ARIA roles, properties and states.</p>
+
+<hr />
+
+<h2 id="scenarios">Page Loading Scenarios</h2>
+<p>For the purposes of keeping examples simple, we use a basic blog page template for conveying common loading techniques. In reality, blogs by their nature should be highly performant (i.e. fetching cached, static content) and would not require any kind of asyncronous rendering or skeleton placeholders. Please keep this in mind and think very carefully about whether your type of page and architecture actually requires the technical overhead of skeletons or not.</p>
+
+<p>We consider 4 main scenarios for how a full page may be constructed:</p>
+<ol>
+    <li>Buffered (default)</li>
+    <li>Client-Side Rendered (SPA)</li>
+    <li>In-Order Streaming (Progressive Rendering)</li>
+    <li>Out of Order Streaming</li>
+</ol>
+
+<p>Of course this is not the whole story! After the page has been loaded, users may interact with components that trigger <a href="#scenario-5">partial page updates</a>, in which case skeleton placeholders may also be utilized.</p>
+
+<h3 id="scenario-1">Scenario 1: Buffered Rendering</h3>
+<p>With buffered rendering (the default manner in which web pages are loaded) the client waits for the entire HTML to be sent by the server before rendering. Therefore, in this scenario, there is no opportunity to display skeleton placeholders, because the content arrives all at once (one caveat would be a SPA, which we cover in the next section).</p>
+
+<h4>The Empty Screen</h4>
+<p>This example simulates the delay (set to 3 seconds) and empty screen while the client waits for the entire HTML payload from the server.</p>
+<p><a href="../examples/buffered/example-1/">View Example</a></p>
+<p>For many types of web site, so long as the delay is not too long, this empty screen can be a perfectly acceptable user experience and no further optimizations or skeletons are necessary.</p>
+
+<hr />
+
+<h3 id="scenario-2">Scenario 2: Client Side Rendering (SPA)</h3>
+<p>A buffered page load can however be the starting point for a non-isomorphic client-side app, i.e. if the server sends a single script tag as the app entry point. The JavaScript app could then leverage skeletons as content placeholders.</p>
+<p>Fully client-side rendered JavaScript applications (i.e. SPAs) such as this are currently out of scope for this documentation. We may add updates in the future. In general though, many of the concepts of <a href="#scenario-4">out-of-order streaming</a> will apply.</p>
+
+<hr />
+
+<h3 id="scenario-3">Scenario 3: In-Order Streaming (Progressive Rendering)</h3>
+<p>In contrast to buffered rendering, progressive rendering does not have to wait for the entire HTML to arrive from the server. The client receives the HTML in chunks, allowing critical above-the-fold content to be displayed first, meaning less time staring at an empty white screen. For the vast majority of pages using progressive rendering, skeleton placeholders will be unneccessary, as the nature and speed in which content is streamed is a sufficient UX improvement over the "white screen" encountered with buffered rendering.</p>
+<p>The CSS <span class="highlight">:empty</span> technique is highly efficient for this scenario and basic skeleton orchestration. Any kind of complex skeleton orchestration would be better left to <a href="#scenario-4">out-of-order streaming</a>. Remember also, that our Skin skeleton classes cannot be leveraged with this technique; therefore the developer must construct skeletons with their own custom CSS.</p>
+<p>In all examples below we utilize client-side JavaScript to simulate how a server might stream the HTML in chunks to the client.</p>
+
+<h4>One Column with Empty Space</h4>
+<p>Our first progressive rendering example shows how the main article content might be streamed in after the main navigation and featured articles.</p>
+<p><a href="../examples/in-order/example-1a/">View Example</a></p>
+<p>We have added a 3 second delay in order to simulate a service that is slow to fetch the main content. Remember, this is a highly contrived use case! No web site should be taking that long to retrieve static content and therefore would never require a skeleton!</p>
+
+<h4>One Column with Skeleton</h4>
+<p>Now let's add a skeleton placeholder for the main content. Using progressive rendering we stream an opening div tag to the client, and while the server works on getting the next chunk ready, the element will match the CSS :empty rule.</p>
+<p><a href="../examples/in-order/example-1b/">View Example</a></p>
+<p>Okay, that was easy, our white space has been replaced with a skeleton while we wait for the next chunk to arrive. But what about when we have two columns?</p>
+
+<h4>Two Columns with Empty Space</h4>
+<p>To keep things simple lets assume the second column is also static content that will be quickly flushed from the server.</p>
+<p><a href="../examples/in-order/example-2a/">View Example</a></p>
+<p>The goal of a skeleton is to replace empty space with a placeholder graphic giving a rough approximation of the content and layout to come. Lets see if we can update our skeleton to show two columns instead of just one.</p>
+
+<h4>Two Columns with Skeleton</h4>
+<p>Our main column and side column are siblings elements, so we cannot start the side column element without flushing and closing the main column element that precedes it. This means we cannot have an :empty main column and an :empty side column simultaneously.</p>
+<p>With some clever CSS we can create a single background image graphic representing a two column layout on the :empty main column.</p>
+<p><a href="../examples/in-order/example-2b/">View Example</a></p>
+<p>This might be satisfactory in some cases, but what if we want to show the main content without waiting for the side column to be flushed (the side content may be a slow service also)? What about responsive design? How will our two column skeleton respond at various breakpoints?</p>
+<p>At this point we start to see that choreographing more than one skeleton placeholder with in-order streaming can become quite tricky. When we have more than one slow service, and a need for multiple skeleton placeholders, it is time to think about out-of-order streaming, which can eliminate these choreography concerns, but on the flipside has the potential to introduce the dreaded layout shift. Read on to find out more.</p>
+
+<hr />
+
+<h3 id="scenario-4">Scenario 4: Out-of-Order Streaming</h3>
+<p>Out-of-order streaming allows chunks of page content to arrive in any order, e.g. the server could send the chunk for the side column before the chunk for the main column. This technique does require some client-side JavaScript to re-assemble the DOM in the correct order as pieces arrive.</p>
+<p>Out-of-order streaming also has parallels with client-side rendered SPAs, as those apps might typically render content based on the order in which their fetch requests come in.</p>
+<p>In all examples below we utilize client-side JavaScript to simulate an out-of-order streaming experience.</p>
+
+<h4>Layout Shift</h4>
+<p>With our in-order streaming examples, the appereance of new content was always <em>appended</em>, therefore never caused existing content or layout to move. Let's see what happens when we stream in our main content, side column and footer out of order.</p>
+<p><a href="../examples/out-of-order/example-1/">View Example</a></p>
+<p>As the content is loading, try clicking on the link in the footer. Now imagine if it were an "Add to Cart" or "Buy Now" button and how infuriating that would be. Imagine being a keyboard user, and the element with keyboard focus being pushed down the page out of view</p>
+<p>So, while getting content to the user faster always sounds like a good idea in theory, this example showcases how it can cause some unintended consequences and a poor UX.</p>
+<p>The good news is that skeletons, under certain conditions, have the ability to mitigate or mask entirely the problems associated with content arriving out-of-order.</p>
+
+<h4>Reserving Space</h4>
+<p>Skeletons can prevent the layout shift associated with out-of-order streaming by reserving the physical space for that content.</p>
+<p><a href="../examples/out-of-order/example-2/">View Example</a></p>
+<p>The physical dimensions of the reserved space must be known ahead of time. When skeletons reserve the right amount of space, they will prevent layout from shifting. When they reserve too much or too little, layout will shift.</p>
+<p>For some kinds of content, we can be sure of the physical dimensions ahead of time, images, videos, carousels, for example. For text however, we can only approximate in most cases, and therefore blocks of text make poor candidates for skeletons.</p>
+
+<h4>Skeleton-itis</h4>
+<p>With in order streaming and the :empty technique, it is not possible to display more than one skeleton concurrently. With out-of-order streaming, this restriction is lifted. This is both a good and a bad thing.</p>
+<p>Let's see what happens when we create skeletons for all main page sections.</p>
+<p><a href="../examples/out-of-order/example-3/">View Example</a></p>
+<p>Compare this with our <a href="../examples/out-of-order/example-2/">previous example</a> or <a href="../examples/in-order/example-2b/">In-Order streaming</a>. The wait time for the main content is the same, but without any shift or flashing in-and-out of skeletons. Most web pages should not have a 1:1 mapping of page sections to skeletons!</p>
+
+<h4>Out-of-order Placeholders Only</h4>
+<p>Perhaps there is a compromise? We have established that to avoid unexpected layout shift, skeletons must reserve exactly the same amount of space as the content. The exception to this rule is if the skeleton and its content is appended to the page.</p>
+<p>Out-of-order streaming allows us to lay down our placeholders all at the same time and reserve space <em>without</em> waiting for the rest of the page. We can then sequence the streaming in a way that only ever appends the content.</p>
+<p><a href="../examples/out-of-order/example-4/">View Example</a></p>
+<p>While this might seem to defeat the purpose of out-of-order streaming (i.e. getting content onscreen quicker, regardless of its position) this does provide us with one method of tackling undesired layout shift and gaining some of the perceived performance increase of skeletons.</p>
+
+<hr />
+
+<h3 id="scenario-5">Scenario 5: Partial Page Updates</h3>
+<p>So far, our emphasis has been on the initial page load, but skeletons are also useful (perhaps even more so) for partial page updates, i.e. when a user interface component triggers a request for additional content from the server.</p>
+<p>Two common examples are loading in more content to any section of the page (e.g. a "see more" button) and refreshing the content of a section (e.g. by changing a search filter).</p>
+<p>It is important to note that any layout shift that happens <strong>immediately</strong> upon click of a button would not be classed as unexpected. However, if the layout shifts again, after some amount of time (i.e. after a wait for data to be fetched), then this would be classed as unexpected (because the user triggered that action). Again, skeletons can help in this scenario by reserving physical space until the actual content is ready.</p>
+
+<h4>Load More - Unpredictable Size</h4>
+<p>This example shows an initial expected layout shift upon clicking the load more button. After a 3 second wait we experience an unexpected layout shift (i.e. the button is shunted down the page) due to the skeletons not reserving the same amount of physical space as the content that is fetched.</p>
+<p><a href="../examples/csr/example-1/">View Example</a></p>
+<p>Each item that is loaded has an arbitrary amount of text. How could we make it less arbitrary and more predictable?</p>
+
+<h4>Load More - Predictable Size</h4>
+<p>One way to make content length less arbitrary is via text truncation. In this example the content has been truncated to two lines, meaning we can be more sure about the physical space that needs to be reserved by the skeleton.</p>
+<p><a href="../examples/csr/example-2/">View Example</a></p>
+<p>Again though it is worth remembering, working with text is far less predictable than with images, video and the like. The more predictable the type of content and its size and shape, the better skeletons will work to mitigate layout shift.</p>
+
+<h4>Refreshing Content</h4>
+<p>In addition to adding more content to any section of the page, another common scenario is to refresh the content of an existing area of the page. For example, paginating to the next set of results, or refreshing a set of thumbnail images.</p>
+<p>Just as with loading more content, refreshing a section of content can fall afoul of layout shift if the content size is <a href="../examples/csr/example-3/">unpredictable</a>. Again the situation can be avoided with <a href="../examples/csr/example-4/">predictable</a> content size.</p>