Editorial: clean up small parts of sequential focus navigation (whatwg#10632)

Author: domfarolino

source

@@ -80292,10 +80292,10 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
 
   <h4><dfn>Sequential focus navigation</dfn></h4>
 
-  <p>Each <code>Document</code> has a <dfn>sequential focus navigation order</dfn>, which orders some
-  or all of the <span data-x="focusable area">focusable areas</span> in the <code>Document</code>
-  relative to each other. Its contents and ordering are given by the <span>flattened
-  tabindex-ordered focus navigation scope</span> of the <code>Document</code>.</p>
+  <p>Each <code>Document</code> has a <dfn>sequential focus navigation order</dfn>, which orders
+  some or all of the <span data-x="focusable area">focusable areas</span> in the
+  <code>Document</code> relative to each other. Its contents and ordering are given by the
+  <span>flattened tabindex-ordered focus navigation scope</span> of the <code>Document</code>.</p>
 
   <p class="note">Per the rules defining the <span>flattened tabindex-ordered focus navigation
   scope</span>, the ordering is not necessarily related to the <span>tree order</span> of the
@@ -80315,10 +80315,21 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
   point</span> to the <span>target element</span> when <span data-x="navigate-fragid">navigating
   to a fragment</span>.</p>
 
+  <p>A <dfn>sequential focus direction</dfn> is one of two possible values: "<dfn><code
+  data-x="sequential-focus-forward">forward</code></dfn>", or "<dfn><code
+  data-x="sequential-focus-backward">backward</code></dfn>". They are used in the below algorithms
+  to describe the direction in which sequential focus travels at the user's request.</p>
+
+  <p>A <dfn>selection mechanism</dfn> is one of two possible values: "<dfn><code
+  data-x="selection-mechanism-DOM">DOM</code></dfn>", or
+  "<dfn><code data-x="selection-mechanism-sequential">sequential</code></dfn>". They are used to
+  describe how the <span>sequential navigation search algorithm</span> finds the <span>focusable
+  area</span> it returns.</p>
+
   <p>When the user requests that focus move from the <span>currently focused area of a top-level
-  traversable</span> to the next or previous <span>focusable area</span> (e.g. as the default
+  traversable</span> to the next or previous <span>focusable area</span> (e.g., as the default
   action of pressing the <kbd><kbd>tab</kbd></kbd> key), or when the user requests that focus
-  sequentially move to a <span>top-level traversable</span> in the first place (e.g. from the
+  sequentially move to a <span>top-level traversable</span> in the first place (e.g., from the
   browser's location bar), the user agent must use the following algorithm:</p>
 
   <ol>
@@ -80332,26 +80343,29 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
    focus navigation starting point</span> instead.</p></li>
 
    <li>
-    <p>Let <var>direction</var> be <i>forward</i> if the user requested the <em>next</em>
-    control, and <i>backward</i> if the user requested the previous control.</p>
+    <p>Let <var>direction</var> be "<code data-x="sequential-focus-forward">forward</code>" if the
+    user requested the next control, and "<code
+    data-x="sequential-focus-backward">backward</code>" if the user requested the previous
+    control.</p>
 
-    <p class="note">Typically, pressing <kbd><kbd>tab</kbd></kbd> requests the next control, and pressing
-    <kbd><kbd>shift</kbd> + <kbd>tab</kbd></kbd> requests the previous control.</p>
+    <p class="note">Typically, pressing <kbd><kbd>tab</kbd></kbd> requests the next control, and
+    pressing <kbd><kbd>shift</kbd> + <kbd>tab</kbd></kbd> requests the previous control.</p>
    </li>
 
    <li>
-    <p><i>Loop</i>: Let <var>selection mechanism</var> be <i>sequential</i> if the <var>starting
-    point</var> is a <span>navigable</span> or if <var>starting point</var> is in its
-    <code>Document</code>'s <span>sequential focus navigation order</span>.</p>
+    <p><i>Loop</i>: Let <var>selection mechanism</var> be "<code
+    data-x="selection-mechanism-sequential">sequential</code>" if <var>starting point</var> is a
+    <span>navigable</span> or if <var>starting point</var> is in its <code>Document</code>'s
+    <span>sequential focus navigation order</span>.</p>
 
-    <p>Otherwise, <var>starting point</var> is not in its <code>Document</code>'s
-    <span>sequential focus navigation order</span>; let <var>selection mechanism</var> be
-    <i>DOM</i>.</p>
+    <p>Otherwise, <var>starting point</var> is not in its <code>Document</code>'s <span>sequential
+    focus navigation order</span>; let <var>selection mechanism</var> be "<code
+    data-x="selection-mechanism-DOM">DOM</code>".</p>
    </li>
 
    <li><p>Let <var>candidate</var> be the result of running the <span>sequential navigation search
    algorithm</span> with <var>starting point</var>, <var>direction</var>, and <var>selection
-   mechanism</var> as the arguments.</p></li>
+   mechanism</var>.</p></li>
 
    <li><p>If <var>candidate</var> is not null, then run the <span>focusing steps</span> for
    <var>candidate</var> and return.</p></li>
@@ -80389,23 +80403,26 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
   </ol>
 
 
-  <p>The <dfn>sequential navigation search algorithm</dfn> consists of the following steps. This
-  algorithm takes three arguments: <var>starting point</var>, <var>direction</var>,
-  and <var>selection mechanism</var>.</p>
+  <p>The <dfn>sequential navigation search algorithm</dfn>, given a <span>focusable area</span>
+  <var>starting point</var>, <span>sequential focus direction</span> <var>direction</var>, and
+  <span>selection mechanism</span> <var>selection mechanism</var>, consists of the following steps.
+  They return a <span>focusable area</span>-or-null.</p>
 
   <ol>
    <li>
     <p>Pick the appropriate cell from the following table, and follow the instructions in that
     cell.</p>
 
-    <p>The appropriate cell is the one that is from the column whose header describes <var>direction</var> and from the first row whose header describes <var>starting point</var> and <var>selection mechanism</var>.</p>
+    <p>The appropriate cell is the one that is from the column whose header describes
+    <var>direction</var> and from the first row whose header describes <var>starting point</var> and
+    <var>selection mechanism</var>.</p>
 
     <table>
      <thead>
       <tr>
        <th>
-       <th> <var>direction</var> is <i>forward</i>
-       <th> <var>direction</var> is <i>backward</i>
+       <th><var>direction</var> is "<code data-x="sequential-focus-forward">forward</code>"
+       <th><var>direction</var> is "<code data-x="sequential-focus-backward">backward</code>"
      <tbody>
       <tr>
        <th><var>starting point</var> is a <span>navigable</span>
@@ -80416,57 +80433,55 @@ dictionary <dfn dictionary>ToggleEventInit</dfn> : <span>EventInit</span> {
        in <var>starting point</var>'s <span data-x="nav-document">active document</span>, if any; or
        else null
       <tr>
-       <th><var>selection mechanism</var> is <i>DOM</i>
+       <th><var>selection mechanism</var> is "<code data-x="selection-mechanism-DOM">DOM</code>"
+       <td>
+        <p>Let <var>candidate</var> be the <span>suitable sequentially focusable area</span>, that
+        appears nearest after <var>starting point</var> in <var>starting point</var>'s
+        <code>Document</code>, in <span>shadow-including tree order</span>, if any; or else null</p>
+
+        <p class="note">In this case, <var>starting point</var> does not necessarily belong to its
+        <code>Document</code>'s <span>sequential focus navigation order</span>, so we'll select the
+        <span data-x="suitable sequentially focusable area">suitable</span> <span data-x="list
+        item">item</span> from that list that comes <em>after</em> <var>starting point</var> in
+        <span>shadow-including tree order</span>.</p>
+       </td>
+       <td>Let <var>candidate</var> be the <span>suitable sequentially focusable area</span>, that
+       appears nearest before <var>starting point</var> in <var>starting point</var>'s
+       <code>Document</code>, in <span>shadow-including tree order</span>, if any; or else null
+      <tr>
+       <th><var>selection mechanism</var> is "<code
+       data-x="selection-mechanism-sequential">sequential</code>"
        <td>Let <var>candidate</var> be the first <span>suitable sequentially focusable area</span>
-       in the <span>home document</span> following <var>starting point</var>, if any; or else null
+       after <var>starting point</var>, in <var>starting point</var>'s <code>Document</code>'s
+       <span>sequential focus navigation order</span>, if any; or else null
        <td>Let <var>candidate</var> be the last <span>suitable sequentially focusable area</span>
-       in the <span>home document</span> preceding <var>starting point</var>, if any; or else null
-      <tr>
-       <th><var>selection mechanism</var> is <i>sequential</i>
-       <td>Let <var>candidate</var> be the first <span>suitable sequentially focusable area</span> in the <span>home sequential focus navigation order</span> following <var>starting point</var>, if any; or else null
-       <td>Let <var>candidate</var> be the last <span>suitable sequentially focusable area</span> in the <span>home sequential focus navigation order</span> preceding <var>starting point</var>, if any; or else null
-
+       before <var>starting point</var>, in <var>starting point</var>'s <code>Document</code>'s
+       <span>sequential focus navigation order</span>, if any; or else null
     </table>
 
     <p>A <dfn>suitable sequentially focusable area</dfn> is a <span>focusable area</span> whose
     <span>DOM anchor</span> is not <span>inert</span> and is <span>sequentially
     focusable</span>.</p>
+   </li>
 
-    <p>The <dfn>home document</dfn> is the <code>Document</code> to which <var>starting point</var>
-    belongs.</p>
-
-    <p>The <dfn>home sequential focus navigation order</dfn> is the <span>sequential focus
-    navigation order</span> to which <var>starting point</var> belongs.</p>
-
-    <p class="note">The <span>home sequential focus navigation order</span> is the <span>home
-    document</span>'s <span>sequential focus navigation order</span>, but is only used when the
-    <var>starting point</var> is in that <span>sequential focus navigation order</span>
-    (when it's not, <var>selection mechanism</var> will be <i>DOM</i>).</p>
-   </li>
-
-  <li><p>If <var>candidate</var> is a <span data-x="reading-flow-item">reading flow item</span> or
-   null, <var>direction</var> is <i>forward</i>, and <var>starting point</var> is in a
-   <span>reading-flow focus navigation scope</span> <var>scope</var>, then let <var>new
-   candidate</var> be the result of running the <span>reading flow sequential navigation search
-   algorithm</span> given <var>candidate</var>, <var>direction</var>, and <var>starting
-   point</var>'s focus navigation <var>scope</var>.</p></li>
-
-   <li><p>If <var>starting point</var> is a <span data-x="reading-flow-item">reading flow
-   item</span>, <var>direction</var> is <i>backward</i>, and <var>starting point</var> is in a
-   <span>reading-flow focus navigation scope</span> <var>scope</var>, then let <var>new
-   candidate</var> be the result of running the <span>reading flow sequential navigation search
-   algorithm</span> given <var>starting point</var>, <var>direction</var>, and <var>starting
-   point</var>'s focus navigation <var>scope</var>.</p></li>
-
-   <li><p>If <var>candidate</var> is a <span>navigable container</span> with a non-null
-   <span>content navigable</span>, then let <var>new candidate</var> be the result of running the
-   <span>sequential navigation search algorithm</span> given <var>candidate</var>'s <span>content
-   navigable</span>, <var>direction</var>, and <i>sequential</i> <!-- shift-tab from the end in
-   https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2855 -->.</p></li>
-
-   <li><p>If <var>new candidate</var> is null, then let <var>starting point</var> be
-   <var>candidate</var>, and return to the top of this algorithm. Otherwise, let
-   <var>candidate</var> be <var>new candidate</var>.</p></li>
+   <li>
+    <p>If <var>candidate</var> is a <span>navigable container</span> with a non-null <span>content
+    navigable</span>, then:</p>
+
+    <ol>
+     <li><p>Let <var>recursive candidate</var> be the result of running the <span>sequential
+     navigation search algorithm</span> with <var>candidate</var>'s <span>content navigable</span>,
+     <var>direction</var>, and "<code
+     data-x="selection-mechanism-sequential">sequential</code>".<!-- shift-tab from the end in
+     https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2855 --></p></li>
+
+     <li><p>If <var>recursive candidate</var> is null, then return the result of running the
+     <span>sequential navigation search algorithm</span> with <var>candidate</var>,
+     <var>direction</var>, and <var>selection mechanism</var>.</p></li>
+
+     <li><p>Otherwise, set <var>candidate</var> to <var>recursive candidate</var>.</p></li>
+    </ol>
+   </li>
 
    <li><p>Return <var>candidate</var>.</p></li>
   </ol>