From 97a14d95410603835891336d159e67666508d6a3 Mon Sep 17 00:00:00 2001
From: Di Zhang <dizhangg@chromium.org>
Date: Tue, 3 Dec 2024 17:18:04 -0500
Subject: [PATCH] Review changes: refactor example

---
 source | 199 ++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 153 insertions(+), 46 deletions(-)

diff --git a/source b/source
index fa863c03e6e..93e045fd4fc 100644
--- a/source
+++ b/source
@@ -79848,10 +79848,10 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
    is a negative integer.</p></li>
   </ul>
 
-  <p>By default, the order within a <span>tabindex-ordered focus navigation scope</span> is
-  determined by each of its element's <span>tabindex value</span>. This ordering criteria is
-  sometimes overridden, as is the case with <span data-x="reading-flow-ordered focus navigation
-  scope">reading-flow-ordered focus navigation scopes</span>.</p>
+  <p>By default, the order within a <span>tabindex-ordered focus navigation scope</span> is determined
+  by each element's <span>tabindex value</span>. This ordering criteria is sometimes overridden, as is
+  the case with <span data-x="reading-flow-ordered focus navigation scope">reading-flow-ordered focus
+  navigation scopes</span>.</p>
 
   <p>A <dfn>reading-flow-ordered focus navigation scope</dfn> is a <span>tabindex-ordered focus
   navigation scope</span> whose <span>focus navigation scope owner</span> is a
@@ -80097,7 +80097,7 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
   <p>A <dfn>reading-flow-ordered scope owner</dfn> is either: <ref>CSSDISPLAY</ref></p>
 
   <ul>
-   <li><p>a <span>reading flow container</span>.</p></li>
+   <li><p>a <span>reading flow container</span>, or</p></li>
 
    <li><p>an element <span>delegating its rendering to its children</span> whose <span>CSS parent
    box</span> is a <span>reading flow container</span>.</p></li>
@@ -80109,10 +80109,11 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
   <p>A <dfn>reading flow item</dfn> is an element whose <span>parent element</span> is a
   <span>reading-flow-ordered scope owner</span>.</p>
 
-  <p>The <dfn>reading flow order</dfn> of a <span>reading-flow-ordered focus navigation scope</span> <var>scope</var> is the ordered list of elements constructed as follows:</p>
+  <p>The <dfn>reading flow order</dfn> of a <span>reading-flow-ordered focus navigation scope</span>
+  <var>scope</var> is the ordered list of elements constructed as follows:</p>
 
   <ol>
-   <li><p>Let <var>output</var> be an empty <span>list</span>.</p></li>
+   <li><p>Let <var>output</var> be « ».</p></li>
 
    <li><p>Let <var>owner</var> be the <span>focus navigation scope owner</span> of
    <var>scope</var>.</p></li>
@@ -80142,16 +80143,27 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
         </ol>
        </li>
 
+       <p class="note"> Different <var>item</var>s can have the same <span>inclusive ancestor</span>.
+       Only add to <var>output</var> if it is not already in the <span>reading flow order</span>. This
+       loop stops when the <span>inclusive ancestor</span> of <var>item</var> within the <span>flat
+       tree</span> is in the <var>scope</var>.</p>
+
        <li><p>Set <var>item</var> to the parent element of <var>item</var> within the <span>flat
        tree</span>.</p></li>
       </ol>
      </li>
     </ol>
+
+    <p class="note">The <span>rendering-defined sibling reading flow</span> includes <span
+    data-x="descendant">descendants</span> of the <span>reading flow container</span> that are not in
+    the <span>reading-flow-ordered focus navigation scope</span>. This step traverses the <span
+    data-x="inclusive ancestor">inclusive ancestors</span> of <var>item</var> within the <span>flat
+    tree</span> to find a potential element to include in the <var>reading flow order</var>.</p>
    </li>
 
    <li>
-    <p><span data-x="list iterate">For each</span> <var>child</var> of <var>owner</var> element's
-    children:</p>
+    <p><span data-x="list iterate">For each</span> <var>child</var> of <var>owner</var> element's <span
+    data-x="concept-tree-child">children</span>, in <span>tree order</span>:</p>
     <ol>
      <li><p>If <var>child</var>'s <span>focus navigation scope owner</span> is <var>owner</var> and
      <var>output</var> does not <span data-x="list contains">contain</span> <var>child</var>, <span
@@ -80160,12 +80172,13 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
    </li>
 
    <li><p>Return <var>output</var>.</p></li>
-
   </ol>
 
-  <div class="example">
+  </div>
 
-   <p>The following shows an example of how to compute the reading flow order.</p>
+  <div class="example">
+   <p>The following example shows how to get the <span>flattened tabindex-ordered focus navigation
+   scope</span> for <code data-x="">wrapper</code>.</p>
 
    <pre><code class="html">&lt;!DOCTYPE html>
 &lt;html lang="en">
@@ -80194,60 +80207,154 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
 &lt;/body>
 &lt;/html></code></pre>
 
-    <p><img src="/images/reading-flow-order-example.svg" width="500" height="350" alt=""
-    class="darkmode-aware"></p>
+   <p><img src="/images/reading-flow-order-example.svg" width="500" height="350" alt=""
+   class="darkmode-aware"></p>
 
-    <p>For a reading-flow-ordered focus navigation scope where wrapper is the focus scope owner:</p>
+   <p>In this example, <code data-x="">wrapper</code> is the <span>focus navigation scope owner</span>
+   of a <span>reading-flow-ordered focus navigation scope</span> and a <span>reading flow
+   container</span>. Its <span>reading flow order</span> is computed as follows:</p>
 
-    <ol>
-     <li><p>Let output be [].</p></li>
+   <ul>
+    <li><p>Per step 4, we get <code data-x="">wrapper</code>'s <span>rendering-defined sibling
+    reading flow</span> <var>items</var> as « <code data-x="">A</code>, <code data-x="">F</code>,
+    <code data-x="">C</code>, <code data-x="">H</code> ».</p></li>
 
-     <li><p>Let owner be wrapper.</p></li>
+    <li>
+     <p>Per step 5, we loop through <var>items</var>:</p>
 
-     <li><p>Let container be wrapper.</p></li>
+     <ul>
+      <li><p><code data-x="">A</code>'s <span>focus navigation scope owner</span> is <code
+      data-x="">wrapper</code>, it is added to <var>output</var>.</p></li>
 
-     <li><p>The rendering-defined sibling reading flow is sorted by the CSS order attribute. The
-     items list is [A, F, C, H]. </p></li>
+      <li>
+       <p><code data-x="">F</code>'s <span>focus navigation scope owner</span> is <code
+       data-x="">DC</code>.</p>
 
-     <li><p>Looping through the items, F and C do not have wrapper as its owner, but its parent DC
-     do. Output is now [A, DC, H].</p></li>
+       <ul>
+        <li><p>Set <var>item</var> to be <code data-x="">F</code>'s parent element within the
+        <span>flat tree</span>, <code data-x="">DC</code>.</p></li>
 
-     <li><p>Looping through the children of wrapper, we find PA as not visited reading flow item of
-     owner. Output is now [A, DC, H, PA].</p></li>
+        <li><p><code data-x="">DC</code>'s <span>focus navigation scope owner</span> is <code
+        data-x="">wrapper</code>, it is added to <var>output</var>.</p></li>
+       </ul>
+      </li>
 
-     <li><p>Return output [A, DC, H, PA].</p></li>
-    </ol>
+      <li>
+       <p><code data-x="">C</code>'s <span>focus navigation scope owner</span> is <code
+       data-x="">DC</code>.</p>
 
-    <p>For a reading-flow-ordered focus navigation scope where display: contents DC is the focus
-    scope owner:</p>
+       <ul>
+        <li><p>Set <var>item</var> to be <code data-x="">C</code>'s parent element within the
+        <span>flat tree</span>, <code data-x="">DC</code>.</p></li>
 
-    <ol>
-     <li><p>Let output be [].</p></li>
+        <li><p><code data-x="">DC</code>'s <span>focus navigation scope owner</span> is <code
+        data-x="">wrapper</code>, but it is already in <var>output</var>.</p></li>
+       </ul>
+      </li>
+
+      <li><p><code data-x="">H</code>'s <span>focus navigation scope owner</span> is <code
+      data-x="">wrapper</code>, it is added to <var>output</var>.</p></li>
 
-     <li><p>Let owner be DC.</p></li>
+      <li><p><var>output</var> is « <code data-x="">A</code>, <code data-x="">DC</code>, <code
+      data-x="">H</code> ».</p></li>
+     </ul>
+    </li>
 
-     <li><p>Let container be wrapper.</p></li>
+    <li>
+     <p>Per step 6, we loop through the <span data-x="concept-tree-child">children</span> of <code
+     data-x="">wrapper</code> in <span>tree order</span>:</p>
 
-     <li><p>The rendering-defined sibling reading flow is sorted by the CSS order attribute. The
-     items list is [A, F, C, H]. </p></li>
+     <ul>
+      <li><p><code data-x="">A</code> is already in <var>output</var>.</p></li>
 
-     <li><p>Looping through the items, only F and C's owner is DC. Output is now [F, C].</p></li>
+      <li><p><code data-x="">DC</code> is already in <var>output</var>.</p></li>
 
-     <li><p>Looping through the children of DC, there are no more child to append.</p></li>
+      <li><p><code data-x="">PA</code>'s <span>focus navigation scope owner</span> is <code
+      data-x="">wrapper</code>, it is added to <var>output</var>.</p></li>
 
-     <li><p>Return output [F, C].</p></li>
-    </ol>
+      <li><p><code data-x="">H</code> is already in <var>output</var>.</p></li>
 
-    <p>Note that A, C, F, PA and H are focus scope owners because they are reading flow items. They
-    will follow a tabindex-ordered focus navigation scope and the ordering is not affected by the
-    CSS reading-flow property. In the focus navigation scope of C, the focus order will be [E, D]
-    because E has a positive tabindex.</p>
+      <li><p><var>output</var> is « <code data-x="">A</code>, <code data-x="">DC</code>, <code
+      data-x="">H</code>, <code data-x="">PA</code> ».</p></li>
+     </ul>
+    </li>
+   </ul>
 
-    <p>Combining everything together, the flattened tabindex-ordered focus navigation scope is:
-    [Wrapper, A, B, DC, F, C, E, D, H, PA, G].</p>
+   <p>Notice that <code data-x="">DC</code> is the <span>focus navigation scope owner</span> of a
+   <span>reading-flow-ordered focus navigation scope</span>, but its <span>reading flow
+   container</span> is still <code data-x="">wrapper</code>. Its <span>reading flow order</span> is
+   computed as follows:</p>
 
-  </div>
+   <ul>
+    <li><p>Per step 4, we again get <code data-x="">wrapper</code>'s <span>rendering-defined sibling
+    reading flow</span> <var>items</var> as « <code data-x="">A</code>, <code data-x="">F</code>,
+    <code data-x="">C</code>, <code data-x="">H</code> ».</p></li>
+
+    <li>
+     <p>Per step 5, we loop through <var>items</var>:</p>
+
+     <ul>
+      <li>
+       <p><code data-x="">A</code>'s <span>focus navigation scope owner</span> is <code
+       data-x="">wrapper</code>.</p>
+
+       <ul>
+        <li><p>Set <var>item</var> to be <code data-x="">A</code>'s parent element within the
+        <span>flat tree</span>, <code data-x="">wrapper</code>.</p></li>
+
+        <li><p>While loop ends because <var>item</var> is the <var>container</var>.</p></li>
+       </ul>
+      </li>
+
+      <li><p><code data-x="">F</code>'s <span>focus navigation scope owner</span> is <code
+      data-x="">DC</code>, it is added to <var>output</var>.</p></li>
+
+      <li><p><code data-x="">C</code>'s <span>focus navigation scope owner</span> is <code
+      data-x="">DC</code>, it is added to <var>output</var>.</p></li>
+
+      <li>
+       <p><code data-x="">H</code>'s <span>focus navigation scope owner</span> is <code
+       data-x="">wrapper</code>.</p>
+
+       <ul>
+        <li><p>Set <var>item</var> to be <code data-x="">H</code>'s parent element within the
+        <span>flat tree</span>, <code data-x="">wrapper</code>.</p></li>
+
+        <li><p>While loop ends because <var>item</var> is the <var>container</var>.</p></li>
+       </ul>
+      </li>
+
+      <li><p><var>output</var> is « <code data-x="">F</code>, <code data-x="">C</code> ».</p></li>
+     </ul>
+    </li>
+
+    <li>
+     <p>Per step 6, we loop through the <span data-x="concept-tree-child">children</span> of <code
+     data-x="">wrapper</code> in <span>tree order</span>:</p>
+
+     <ul>
+      <li><p><code data-x="">C</code> is already in <var>output</var>.</p></li>
+
+      <li><p><code data-x="">F</code> is already in <var>output</var>.</p></li>
+
+      <li><p><var>output</var> is « <code data-x="">F</code>, <code data-x="">C</code> ».</p></li>
+     </ul>
+    </li>
+   </ul>
 
+   <p><code data-x="">A</code>, <code data-x="">C</code>, <code data-x="">F</code>, <code
+   data-x="">PA</code> and <code data-x="">H</code> are <span data-x="reading flow item">reading flow
+   items</span>. Each is the <span>focus navigation scope owner</span> of a <span>tabindex-ordered
+   focus navigation scope</span> that does not follow the <span>reading flow order</span>. For example,
+   the <span>focus navigation scope</span> of C will be « <code data-x="">E</code>, <code
+   data-x="">D</code> » because <code data-x="">E</code> has a higher positive <span>tabindex
+   value</span> than <code data-x="">D</code>.</p>
+
+   <p>Combining everything together, the <span>flattened tabindex-ordered focus navigation scope</span>
+   for <code data-x="">wrapper</code> is « <code data-x="">wrapper</code>, <code data-x="">A</code>,
+   <code data-x="">B</code>, <code data-x="">DC</code>, <code data-x="">F</code>, <code
+   data-x="">C</code>, <code data-x="">E</code>, <code data-x="">D</code>, <code data-x="">H</code>,
+   <code data-x="">PA</code>, <code data-x="">G</code> ».</p>
   </div>
 
   <div w-nodev>