Add the inert attribute and tweak definition of inert subtrees

Co-authored-by: Alice Boxhall <[email protected]>

source

@@ -75069,41 +75069,62 @@ END:VCARD</pre>
 
   <h3>Inert subtrees</h3>
 
-  <p class="note">This section <strong>does not</strong> define or create any content attribute
-  named "inert". This section merely defines an abstract <em>concept</em> of
-  <span data-x="inert">inertness</span>.</p>
+  <p class="note">See also <code data-x="attr-inert">inert</code> for an explanation of the
+  attribute of the same name.</p>
 
   <p>A node (in particular elements and text nodes) can be marked as <dfn>inert</dfn>. When a node
-  is <span>inert</span>, then the user agent must act as if the node was absent for the purposes of
-  targeting user interaction events, may ignore the node for the purposes of
-  <span>find-in-page</span>, and may prevent the user from selecting text in that node. User agents
-  should allow the user to override the restrictions on search and text selection, however.</p>
+  is <span>inert</span>:</p>
+
+  <ul>
+   <li><p>Hit-testing must act as if the <dfn
+   data-x-href="https://drafts.csswg.org/css-ui-4/#pointer-events-control"><code>pointer-events</code></dfn>
+   CSS property were set to <dfn><code data-x="inert-pointerEvents-none">none</code></dfn></p></li>
 
-  <p class="example">For example, consider a page that consists of just a single <span>inert</span>
-  paragraph positioned in the middle of a <code>body</code>. If a user moves their pointing device
-  from the <code>body</code> over to the <span>inert</span> paragraph and clicks on the paragraph,
-  no <code data-x="event-mouseover">mouseover</code> event would be fired, and the <code
-  data-x="event-mousemove">mousemove</code> and <code data-x="event-click">click</code> events would
-  be fired on the <code>body</code> element rather than the paragraph.</p>
+   <li><p>Selecting and editing text in that node must be prevented by the user agent.</p></li>
+
+   <li><p>The user agent may ignore the node for the purposes of text search user interfaces
+   (commonly known as "find in page").</p></li>
+  </ul>
 
-  <p class="note">When a node is inert, it generally cannot be focused. Inert nodes that are <span
-  data-x="concept-command">commands</span> will also get disabled.</p>
+  <p class="note">Inert nodes generally cannot be focused. Inert nodes that are <span
+   data-x="concept-command">commands</span> will also get disabled.</p>
+
+  <p>User agents may allow the user to override the restrictions on search, text selection,
+  however.</p>
+
+  <p>By default, an element is not <span>inert</span>.</p>
 
   <p>A <code>Document</code> <var>document</var> is <dfn>blocked by a modal dialog</dfn>
   <var>subject</var> if <var>subject</var> is the topmost <code>dialog</code> element in
   <var>document</var>'s <span>top layer</span>. While <var>document</var> is so blocked, every node
   that is <span>connected</span> to <var>document</var>, with the exception of the
-  <var>subject</var> element and its <span data-x="shadow-including descendant">shadow-including
-  descendants</span>, must be marked <span>inert</span>. (The elements excepted by this paragraph
-  can additionally be marked <span>inert</span> through other means; being part of a modal dialog
-  does not "protect" a node from being marked <span>inert</span>.)</p>
+  <var>subject</var> element and its <span>flat tree</span> descendants, must be marked
+  <span>inert</span>. (The elements excepted by this paragraph can additionally be marked
+  <span>inert</span> through other means; being part of a modal dialog does not "protect" a node
+  from being marked <span>inert</span>.)</p>
 
   <p class="note">The <code>dialog</code> element's <code
-  data-x="dom-dialog-showModal">showModal()</code> method causes this mechanism to trigger, by <span
-  data-x="top-layer-add">adding</span> the <code>dialog</code> element to its <span>node
+  data-x="dom-dialog-showModal">showModal()</code> method causes this mechanism to trigger, by
+  <span data-x="top-layer-add">adding</span> the <code>dialog</code> element to its <span>node
   document</span>'s <span>top layer</span>.</p>
 
+  <h4>The <dfn data-x="attr-inert"><code>inert</code></dfn> attribute</h4>
+
+  <p>The <code data-x="attr-inert">inert</code> attribute is a <span>boolean attribute</span> that
+  indicates, by its presence, that the element and all its <span>flat tree</span> descendants are
+  to be made <span>inert</span> by the user agent.</p>
+
+  <p class="note">By default, there is no persistent visual indication of a subtree being inert.
+  Authors are encouraged to clearly mark what parts of their document are active and which are
+  inert, to avoid user confusion. In particular, it is worth remembering that not all users can see
+  all parts of a page at once; for example, users of screen readers, users on small devices or
+  with magnifiers, and even users just using particularly small windows might not be able to see
+  the active part of a page and might get frustrated if inert sections are not obviously inert. For
+  individual controls, the <code data-x="attr-fe-disabled">disabled</code> attribute is probably
+  more appropriate.</p>
 
+  <p>The <dfn data-x="dom-inert"><code>inert</code></dfn> IDL attribute must <span>reflect</span>
+  the content attribute of the same name.</p>
 
   <h3>Tracking <dfn export>user activation</dfn></h3>