Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a049765
Editorial: clean up small parts of sequential focus
domfarolino Sep 18, 2024
8468c49
Clean up recursion
domfarolino Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 70 additions & 50 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80214,10 +80214,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
Expand All @@ -80237,10 +80237,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>
Expand All @@ -80254,26 +80265,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>
Expand Down Expand Up @@ -80311,23 +80325,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>
Expand All @@ -80338,45 +80355,48 @@ 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>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 <span>tree order</span>, in <var>starting point</var>'s
<code>Document</code>, 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
before <var>starting point</var>, in <span>tree order</span>, in <var>starting point</var>'s
<code>Document</code>, 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

<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>
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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please see my question in the WHATWG matrix chat about this. I'm concerned that the old spec (and thus the spec after this PR) have no material difference between "DOM" and "sequential" selection mode. The note below the home sequential focus navigation order dfn says the only difference is that in the "DOM" selection mode, <var>starting point</var> is not in its own Document's sequential focus navigation order. But that shouldn't actually impact the assignment of <var>candidate</var>, since candidate will always be selected from the starting point's sequential focus navigation order anyways.

So I'm not sure what to do here. Either I am right, and there is no observable difference between the two mechanisms in this case, or it is the intention of the spec to have a difference between the two. I.e., maybe:

  • In the "DOM" case, <var>candidate</var> should be pulled from the DOM in tree order relative to starting point (not necessarily coming from the starting point's Document's "sequential focus navigation order"
  • In the "sequential" case, <var>candidate</var> should be pulled from the subset of the DOM that is included in the starting point's Document's "sequential focus navigation order"

<td>Let <var>candidate</var> be the last <span>suitable sequentially focusable area</span>
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>

<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>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> with <var>candidate</var>'s <span>content
navigable</span> as the first argument, <var>direction</var> as the second, and
<i>sequential</i> <!-- shift-tab from the end in
https://software.hixie.ch/utilities/js/live-dom-viewer/?saved=2855 --> as the third.</p>

<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>
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>

<p>Otherwise, set <var>candidate</var> to <var>recursive candidate</var>.</p>
</li>
</ol>
</li>

<li><p>Return <var>candidate</var>.</p></li>
Expand Down