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

Merged
merged 5 commits into from
Oct 2, 2024
Merged

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

Changes from all commits
Commits
Show all changes
5 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
542daa4
Wording + note
domfarolino Sep 29, 2024
3d2cf01
shadow-including tree order
domfarolino Oct 2, 2024
74e06a8
Address review
domfarolino Oct 2, 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
128 changes: 77 additions & 51 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,54 @@ 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>
domfarolino marked this conversation as resolved.
Show resolved Hide resolved

<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
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
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>

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

<li><p>Otherwise, set <var>candidate</var> to <var>recursive candidate</var>.</p></li>
</ol>
domfarolino marked this conversation as resolved.
Show resolved Hide resolved
</li>

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