Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Clarify and add some examples around focus
Closes whatwg#1972. Notable changes:

- Merges the two definitions of "expressly inert" for dialogs and other elements; they were equivalent.
- Regroups some sentences in the "Data model" section so that related concepts stay together, separated by <hr>s.
- Add examples for what "expressly disabled" means.
- Add an example of "focus fixup rule one"
- Fixed "focus fixup rule one" to talk correctly about "focusable areas", not "focused areas".
  • Loading branch information
domenic authored and Alice Boxhall committed Jan 7, 2019
1 parent c663d3d commit 3bcf4bf
Showing 1 changed file with 71 additions and 48 deletions.
119 changes: 71 additions & 48 deletions source
Expand Up @@ -71814,10 +71814,9 @@ END:VCARD</pre>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-1">
Elements that have their <span>tabindex focus flag</span> set, that are not <span
data-x="concept-element-disabled">actually disabled</span>, that are not <span
data-x="expressly inert control">expressly inert</span>, and that are either <span>being
rendered</span> or <span>being used as relevant canvas fallback content</span>. <!--
CANVAS-FOCUS-FALLBACK -->
data-x="concept-element-disabled">actually disabled</span>, that are not <span>expressly
inert</span>, and that are either <span>being rendered</span> or <span>being used as relevant
canvas fallback content</span>. <!-- CANVAS-FOCUS-FALLBACK -->
<td headers="td-fa-1 th-fa-dom-rep">
The element itself.
<tr>
Expand All @@ -71830,8 +71829,8 @@ END:VCARD</pre>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-2">
The shapes of <code>area</code> elements in an <span>image map</span> associated with an
<code>img</code> element that is <span>being rendered</span> and is not <span data-x="expressly
inert control">expressly inert</span>.
<code>img</code> element that is <span>being rendered</span> and is not <span>expressly
inert</span>.
<td headers="td-fa-2 th-fa-dom-rep">
The <code>img</code> element.
<tr>
Expand All @@ -71851,8 +71850,8 @@ END:VCARD</pre>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-3">
The user-agent provided subwidgets of elements that are <span>being rendered</span> and are not
<span data-x="concept-element-disabled">actually disabled</span> or <span data-x="expressly
inert control">expressly inert</span>.
<span data-x="concept-element-disabled">actually disabled</span> or <span>expressly
inert</span>.
<td headers="td-fa-3 th-fa-dom-rep">
The element for which the <span>focusable area</span> is a subwidget.
<tr>
Expand All @@ -71868,8 +71867,8 @@ END:VCARD</pre>
<tbody>
<tr>
<th class="data-header" headers="th-fa-area" id="td-fa-4">
The scrollable regions of elements that are <span>being rendered</span> and are not <span
data-x="expressly inert control">expressly inert</span>. <!-- the being rendered part is kinda
The scrollable regions of elements that are <span>being rendered</span> and are not
<span>expressly inert</span>. <!-- the being rendered part is kinda
redundant, a scrollable region is a box generated for the element so by definition if the
element has a scrollable region it is being rendered -->
<td headers="td-fa-4 th-fa-dom-rep">
Expand Down Expand Up @@ -71941,41 +71940,53 @@ END:VCARD</pre>
object</span>'s <span>control group</span>.</p>

<div class="example">
<p>Thus:</p>

<p>Thus, a <span>viewport</span> always belongs to the <span>control group</span> of the
<code>Document</code> for which the <span>viewport</span> was created, an <code>input</code>
control belongs to the <span>control group</span> of its nearest ancestor <code>dialog</code> or
<code>Document</code>, and an image map's shapes belong to the nearest ancestor
<code>dialog</code> or <code>Document</code> of the <code>img</code> elements (not the
<code>area</code> elements &mdash; this means one <code>area</code> element might create multiple
shapes in different <span data-x="control group">control groups</span>).</p>
<ul>
<li><p>A <span>viewport</span> always belongs to the <span>control group</span> of the
<code>Document</code> for which the <span>viewport</span> was created.</p></li>

<li><p>An <code>input</code> control belongs to the <span>control group</span> of its nearest
ancestor <code>dialog</code> or <code>Document</code>.</p></li>

<li><p>An image map's shapes belong to the nearest ancestor <code>dialog</code> or
<code>Document</code> of the <code>img</code> elements (not the <code>area</code> elements
&mdash; this means one <code>area</code> element might create multiple shapes in different
<span data-x="control group">control groups</span>).</p></li>
</ul>
</div>

<p class="note">It is possible for a <span>control group</span> to be empty, i.e. for it to have
no <span data-x="focusable area">focusable areas</span>.</p>

<p>An element is <dfn data-x="expressly inert control">expressly inert</dfn> if it is
<span>inert</span> but it is not a <span>control group owner object</span> and its nearest
ancestor <span>control group owner object</span> is not <span>inert</span>.</p>
<hr>

<p>One <span>focusable area</span> in each non-empty <span>control group</span> is designated the
<dfn>focused area of the control group</dfn>. Which control is so designated changes over time,
based on algorithms in this specification. If a <span>control group</span> is empty, it has no <span
data-x="focused area of the control group">focused area</span>.</p>
<p><span id="expressly-inert-control"></span><span id="expressly-inert-dialog"></span>An element
is <dfn>expressly inert</dfn> if it is <span>inert</span> and its nearest ancestor <span>control
group owner object</span> is not <span>inert</span>.</p>

<div class="example">
<p>In a page with no <code>dialog</code> elements, all elements that are <span>inert</span> are
<span>expressly inert</span>, and vice-versa.</p>

<p>Inside an <span>inert</span> <code>dialog</code> element, all descendant elements are not
<span>expressly inert</span>, even if they are <span>inert</span>.</p>

<p>A <code>dialog</code> element is <span>expressly inert</span> if it is <span>inert</span> and
not nested inside another <span>inert</span> dialog.</p>
</div>

<hr>

<p>Each <span>control group owner object</span> can also act as the <dfn data-x="dialog group
manager">manager</dfn> of a <dfn>dialog group</dfn>.</p>

<p>Each <code>dialog</code> element that has an <code data-x="attr-dialog-open">open</code>
attribute specified and that is <span>being rendered</span> (i.e. that is a <span>control group
owner object</span>) and is not <span data-x="expressly inert dialog">expressly inert</span>
owner object</span>) and is not <span>expressly inert</span>
belongs to the <span>dialog group</span> whose <span data-x="dialog group manager">manager</span> is
the <code>dialog</code> element's nearest ancestor <span>control group owner object</span>.</p>

<p>A <code>dialog</code> is <dfn data-x="expressly inert dialog">expressly inert</dfn> if it is
<span>inert</span> but its nearest ancestor <span>control group owner object</span> is not.</p>

<p>If no <code>dialog</code> element has a particular <span>control group owner object</span> as
its nearest ancestor <span>control group owner object</span>, then that <span>control group owner
object</span> has no <span>dialog group</span>.</p>
Expand All @@ -71984,17 +71995,22 @@ END:VCARD</pre>
dialog of the dialog group</dfn>. Which <code>dialog</code> is so designated changes over time,
based on algorithms in this specification.</p>

<p>Elements in <span data-x="dialog group">dialog groups</span> are ordered in <span>tree
order</span>.</p>

<hr>

<p>One <span>focusable area</span> in each non-empty <span>control group</span> is designated the
<dfn>focused area of the control group</dfn>. Which control is so designated changes over time,
based on algorithms in this specification. If a <span>control group</span> is empty, it has no <span
data-x="focused area of the control group">focused area</span>.</p>

<p><span data-x="focusable area">Focusable areas</span> in <span data-x="control group">control groups</span>
are ordered relative to the <span>tree order</span> of their <span data-x="DOM anchor">DOM
anchors</span>. <span data-x="focusable area">Focusable areas</span> with the same <span>DOM anchor</span> in a
<span>control group</span> are ordered relative to their CSS box's relative positions in a pre-order,
depth-first traversal of the box tree. <ref spec=CSS></p>

<p>Elements in <span data-x="dialog group">dialog groups</span> are ordered in <span>tree
order</span>.</p>

<hr>

<p>The <dfn>currently focused area of a top-level browsing context</dfn> at any particular time is
Expand Down Expand Up @@ -72479,11 +72495,10 @@ END:VCARD</pre>
<p><dfn>Focus fixup rule one</dfn>: When the designated <span data-x="focused area of the control
group">focused area of a control group</span> is removed from that <span>control group</span> in
some way (e.g. it stops being a <span>focusable area</span>, it is removed from the DOM, it
becomes <span data-x="expressly inert control">expressly inert</span>, etc), and the <span>control
group</span> is still not empty: designate the first non-<span>inert</span> <span data-x="focused
area of the control group">focused area</span> in that <span>control group</span> to be the new
<span>focused area of the control group</span>, if any; if they are all <span>inert</span>, then
designate the first <span data-x="focused area of the control group">focused area</span> in that
becomes <span>expressly inert</span>, etc), and the <span>control group</span> is still not
empty: designate the first non-<span>inert</span> <span>focusable area</span> in that
<span>control group</span> to be the new <span>focused area of the control group</span>, if any;
if they are all <span>inert</span>, then designate the first <span>focusable area</span> in that
<span>control group</span> to be the new <span>focused area of the control group</span> regardless
of <span data-x="inert">inertness</span>. If such a removal instead results in the <span>control
group</span> being empty, then there is simply no longer a <span>focused area of the control
Expand All @@ -72494,6 +72509,14 @@ END:VCARD</pre>
also happen to an <code>input</code> element when the element gets <span
data-x="concept-fe-disabled">disabled</span>.</p>

<p class="example">In a <code>Document</code> without <code>dialog</code> elements, whose <span
data-x="focused area of the control group">focused area</span> is a <code>button</code> element,
removing, disabling, or hiding that button would cause the page's new <span data-x="focused area
of the control group">focused area</span> to be the <span>viewport</span> of the
<code>Document</code>. This would, in turn, be reflected through the <code
data-x="dom-document-activeElement">activeElement</code> API as <span>the body
element</span>.</p>

<p><dfn>Focus fixup rule two</dfn>: When a <span>dialog group</span> has no designated <span>focused
dialog of the dialog group</span>, and its <span>dialog group manager</span>'s <span>control
group</span> changes from being non-empty to being empty, the first non-<span>inert</span>
Expand All @@ -72502,18 +72525,18 @@ END:VCARD</pre>
the <span>focused dialog of the dialog group</span>.</p>

<p><dfn>Focus fixup rule three</dfn>: When the designated <span data-x="focused dialog of the
dialog group">focused dialog of a dialog group</span> is removed from that <span>dialog group</span> in
some way (e.g. it stops <span>being rendered</span>, it loses its <code
data-x="attr-dialog-open">open</code> attribute, it becomes <span data-x="expressly inert
dialog">expressly inert</span>, etc), and there is still a <span>dialog group</span> (because the
<code>dialog</code> in question was not the last <code>dialog</code> in that <span>dialog group</span>):
if the <span>dialog group</span>'s <span data-x="dialog group manager">manager</span>'s <span>control
group</span> is non-empty, let there be no designated <span>focused dialog of the dialog group</span>
any more; otherwise (in the case that the <span>control group</span> is empty), designate the first
non-<span>inert</span> <code>dialog</code> in the <span>dialog group</span> to be the <span>focused
dialog of the dialog group</span>, or, if they are all <span>inert</span>, designate the first
<code>dialog</code> in the <span>dialog group</span> to be the <span>focused dialog of the dialog
group</span> regardless of <span data-x="inert">inertness</span>.</p>
dialog group">focused dialog of a dialog group</span> is removed from that <span>dialog
group</span> in some way (e.g. it stops <span>being rendered</span>, it loses its <code
data-x="attr-dialog-open">open</code> attribute, it becomes <span>expressly inert</span>, etc),
and there is still a <span>dialog group</span> (because the <code>dialog</code> in question was
not the last <code>dialog</code> in that <span>dialog group</span>): if the <span>dialog
group</span>'s <span data-x="dialog group manager">manager</span>'s <span>control group</span> is
non-empty, let there be no designated <span>focused dialog of the dialog group</span> any more;
otherwise (in the case that the <span>control group</span> is empty), designate the first
non-<span>inert</span> <code>dialog</code> in the <span>dialog group</span> to be the
<span>focused dialog of the dialog group</span>, or, if they are all <span>inert</span>, designate
the first <code>dialog</code> in the <span>dialog group</span> to be the <span>focused dialog of
the dialog group</span> regardless of <span data-x="inert">inertness</span>.</p>

<p>When the <span>currently focused area of a top-level browsing context</span> was a <span>focusable
area</span> but stops being a <span>focusable area</span>, or when it was a <code>dialog</code> in a
Expand Down

0 comments on commit 3bcf4bf

Please sign in to comment.