Editorial: rearrange ElementInternals into sections

As it's grown over time, some more structure seems nice. This also
updates the section to the latest Web IDL conventions, e.g. "this",
"method steps", etc.

Author: domenic

source

@@ -67280,7 +67280,13 @@ customElements.define("x-foo", class extends HTMLElement {
 
   </div>
 
-  <h4>The <code>ElementInternals</code> interface</h4>
+  <h4>Element internals</h4>
+
+  <p>Certain capabilities are meant to be available to a custom element author, but not to a custom
+  element consumer. These are provided by the <code
+  data-x="dom-attachInternals">element.attachInternals()</code> method, which returns an instance of
+  <code>ElementInternals</code>. The properties and methods of <code>ElementInternals</code> allow
+  control over internal features which the user agent provides to all elements.</p>
 
   <dl class="domintro">
    <dt><var>element</var> . <code subdfn data-x="dom-attachInternals">attachInternals()</code></dt>
@@ -67291,29 +67297,74 @@ customElements.define("x-foo", class extends HTMLElement {
    element definition, or if it is called twice on the same element.</p></dd>
   </dl>
 
+  <div w-nodev>
+
+  <p>Each <code>HTMLElement</code> has an <dfn>attached internals</dfn> boolean, initially
+  false.</p>
+
+  <p>The <dfn><code data-x="dom-attachInternals">attachInternals()</code></dfn> method steps
+  are:</p>
+
+  <ol>
+   <!-- We could lift this restriction in the future. -->
+   <li><p>If <span>this</span>'s <span data-x="concept-element-is-value"><code data-x="">is</code>
+   value</span> is not null, then throw a <span>"<code>NotSupportedError</code>"</span>
+   <code>DOMException</code>.</p></li>
+
+   <li><p>Let <var>definition</var> be the result of <span data-x="look up a custom element
+   definition">looking up a custom element definition</span> given this's <span>node
+   document</span>, its namespace, its local name, and null as the <span
+   data-x="concept-element-is-value"><code data-x="">is</code> value</span>.</p></li>
+
+   <li><p>If <var>definition</var> is null, then throw an
+   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
+
+   <li><p>If <var>definition</var>'s <span
+   data-x="concept-custom-element-definition-disable-internals">disable internals</span> is true,
+   then throw a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
+
+   <li><p>If <span>this</span>'s <span>attached internals</span> is true, then throw an
+   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
+
+   <li><p>If <span>this</span>'s <span>custom element state</span> is not "<code
+   data-x="">precustomized</code>" or "<code data-x="">custom</code>", then throw a
+   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
+
+   <li><p>Set <span>this</span>'s <span>attached internals</span> to true.</p></li>
+
+   <li><p>Return a new <code>ElementInternals</code> instance whose <span
+   data-x="internals-target">target element</span> is <span>this</span>.</p></li>
+  </ol>
+
+  <h5>The <code>ElementInternals</code> interface</h5>
+
+  <p>The IDL for the <code>ElementInternals</code> interface is as follows, with the various operations and attributes
+  defined in the following sections:</p>
+
   <pre><code class="idl">[Exposed=Window]
 interface <dfn>ElementInternals</dfn> {
-  // Form-associated custom elements
+  // <a href="#shadow-root-access">Shadow root access</a>
+  readonly attribute <code>ShadowRoot</code>? <span data-x="dom-ElementInternals-shadowRoot">shadowRoot</span>;
 
+  // <a href="#form-associated-custom-elements">Form-associated custom elements</a>
   undefined <span data-x="dom-ElementInternals-setFormValue">setFormValue</span>((<span>File</span> or <span data-x="idl-USVString">USVString</span> or <span>FormData</span>)? value,
-                    optional (<span>File</span> or <span data-x="idl-USVString">USVString</span> or <span>FormData</span>)? state);
+                         optional (<span>File</span> or <span data-x="idl-USVString">USVString</span> or <span>FormData</span>)? state);
 
   readonly attribute <span>HTMLFormElement</span>? <span data-x="dom-ElementInternals-form">form</span>;
 
   undefined <span data-x="dom-ElementInternals-setValidity">setValidity</span>(optional <span>ValidityStateFlags</span> flags = {},
-                   optional DOMString message,
-                   optional <span>HTMLElement</span> anchor);
+                        optional DOMString message,
+                        optional <span>HTMLElement</span> anchor);
   readonly attribute boolean <span data-x="dom-ElementInternals-willValidate">willValidate</span>;
   readonly attribute <span>ValidityState</span> <span data-x="dom-ElementInternals-validity">validity</span>;
   readonly attribute DOMString <span data-x="dom-ElementInternals-validationMessage">validationMessage</span>;
   boolean <span data-x="dom-ElementInternals-checkValidity">checkValidity</span>();
   boolean <span data-x="dom-ElementInternals-reportValidity">reportValidity</span>();
 
   readonly attribute <span>NodeList</span> <span data-x="dom-ElementInternals-labels">labels</span>;
-
-  readonly attribute <code>ShadowRoot</code>? <span data-x="dom-ElementInternals-shadowRoot">shadowRoot</span>;
 };
 
+// <a href="#accessibility-semantics">Accessibility semantics</a>
 ElementInternals includes <span>ARIAMixin</span>;
 
 dictionary <dfn>ValidityStateFlags</dfn> {
@@ -67329,6 +67380,43 @@ dictionary <dfn>ValidityStateFlags</dfn> {
   boolean customError = false;
 };</code></pre>
 
+  <p>Each <code>ElementInternals</code> has a <dfn data-x="internals-target">target element</dfn>,
+  which is a <span>custom element</span>.</p>
+
+  </div>
+
+  <h5>Shadow root access</h5>
+
+  <dl class="domintro">
+   <dt><var>internals</var> . <code data-x="dom-ElementInternals-shadowRoot">shadowRoot</code></dt>
+   <dd><p>Returns the <code>ShadowRoot</code> for <var>internals</var>'s
+   <span data-x="internals-target">target element</span>, if the
+   <span data-x="internals-target">target element</span> is a <span>shadow host</span>, or null
+   otherwise.</p></dd>
+  </dl>
+
+  <div w-nodev>
+  <p>The <dfn><code data-x="dom-ElementInternals-shadowRoot">shadowRoot</code></dfn> getter steps
+  are:</p>
+
+  <ol>
+   <li><p>Let <var>target</var> be <span>this</span>'s <span data-x="internals-target">target
+   element</span>.</p></li>
+
+   <li><p>If <var>target</var> is not a <span>shadow host</span>, then return null.</p></li>
+
+   <li><p>Let <var>shadow</var> be <var>target</var>'s <span
+   data-x="concept-element-shadow-root">shadow root</span>.</p></li>
+
+   <li><p>If <var>shadow</var>'s <span>available to element internals</span> is false, then return
+   null.</p></li>
+
+   <li><p>Return <var>shadow</var>.</p></li>
+  </ol>
+  </div>
+
+  <h5>Form-associated custom elements</h5>
+
   <dl class="domintro">
    <dt><var>internals</var> . <code data-x="dom-ElementInternals-setFormValue">setFormValue</code>(<var>value</var>)</dt>
    <dd>
@@ -67400,89 +67488,11 @@ dictionary <dfn>ValidityStateFlags</dfn> {
    <dd><p>Returns a <code>NodeList</code> of all the <code>label</code> elements that
    <var>internals</var>'s <span data-x="internals-target">target element</span> is associated
    with.</p></dd>
-
-   <dt><var>internals</var> . <code data-x=""><a href="#dom-ElementInternals-accessibility-idl-get">role</a></code> [ = <var>value</var> ]</dt>
-   <dd><p>Sets or retrieves the default ARIA role for <var>internals</var>'s <span
-   data-x="internals-target">target element</span>, which will be used unless the page author
-   overrides it using the <code data-x="attr-aria-role">role</code> attribute.</p></dd>
-
-   <dt><var>internals</var> . <code data-x=""><a href="#dom-ElementInternals-accessibility-idl-get">aria*</a></code> [ = <var>value</var> ]</dt>
-   <dd><p>Sets or retrieves various default ARIA states or property values for
-   <var>internals</var>'s <span data-x="internals-target">target element</span>, which will be used
-   unless the page author overrides them using the <code data-x="attr-aria-*">aria-*</code>
-   attributes.</p></dd>
-
-   <dt><var>internals</var> . <code data-x="dom-ElementInternals-shadowRoot">shadowRoot</code></dt>
-   <dd><p>Returns the <code>ShadowRoot</code> for <var>internals</var>'s
-   <span data-x="internals-target">target element</span>, if the
-   <span data-x="internals-target">target element</span> is a <span>shadow host</span>, or null
-   otherwise.</p></dd>
   </dl>
 
-  <p>Each <code>ElementInternals</code> has a <dfn data-x="internals-target">target element</dfn>,
-  which is a <span>custom element</span>. <code>ElementInternals</code> provides various operations
-  and attributes to allow control over internal features which the user agent provides to all
-  elements.</p>
-
-  <p>Each <code>HTMLElement</code> has an <dfn>attached internals</dfn> boolean, initially
-  false.</p>
-
-  <p>The <dfn><code data-x="dom-attachInternals">attachInternals()</code></dfn> method on
-  an <code>HTMLElement</code> <var>element</var>, when invoked, must run the following steps:</p>
-
-  <ol>
-   <!-- We could lift this restriction in the future. -->
-   <li><p>If <var>element</var>'s <span data-x="concept-element-is-value"><code
-   data-x="">is</code> value</span> is not null, then throw a
-   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
-
-   <li><p>Let <var>definition</var> be the result of <span
-   data-x="look up a custom element definition">looking up a custom element definition</span> given
-   <var>element</var>'s <span>node document</span>, its namespace, its local name, and null as
-   <span data-x="concept-element-is-value"><code data-x="">is</code> value</span>.</p></li>
-
-   <li><p>If <var>definition</var> is null, then throw an
-   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
-
-   <li><p>If <var>definition</var>'s <span
-   data-x="concept-custom-element-definition-disable-internals">disable internals</span> is true,
-   then throw a <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
-
-   <li><p>If <var>element</var>'s <span>attached internals</span> is true, then throw an
-   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
-
-   <li><p>If <var>element</var>'s <span>custom element state</span> is not "<code
-   data-x="">precustomized</code>" or "<code data-x="">custom</code>", then throw a
-   <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
-
-   <li><p>Set <var>element</var>'s <span>attached internals</span> to true.</p></li>
-
-   <li><p>Create a new <code>ElementInternals</code> instance
-   <span data-x="internals-target">targeting</span> <var>element</var>, and return it.</p></li>
-  </ol>
-
-  <p>The <dfn><code data-x="dom-ElementInternals-shadowRoot">shadowRoot</code></dfn> getter steps are:
-
-  <ol>
-   <li><p>Let <var>target</var> be <code>ElementInternals</code>'s <span
-   data-x="internals-target">target element</span>.</p></li>
-
-   <li><p>If <var>target</var> is not a <span>shadow host</span>, then return null.</p></li>
-
-   <li><p>Let <var>shadow</var> be <var>target</var>'s
-   <span data-x="concept-element-shadow-root">shadow root</span>.</p></li>
-
-   <li><p>If <var>shadow</var>'s <span>available to element internals</span> is false, then return
-   null.</p></li>
-
-   <li><p>Return <var>shadow</var>.</p></li>
-  </ol>
-
-  <hr>
-
   <p>Each <span>form-associated custom element</span> has <dfn
   data-x="face-submission-value">submission value</dfn>. It is used to provide one or more
-  <span data-x="formdata-entry">entries</span> on form submission, and
+  <span data-x="formdata-entry">entries</span> on form submission.
   The initial value of <span data-x="face-submission-value">submission value</span> is null, and
   <span data-x="face-submission-value">submission value</span> can be null, a string, a
   <code>File</code>, or a <span>list</span> of <span data-x="formdata-entry">entries</span>.</p>
@@ -67533,12 +67543,11 @@ dictionary <dfn>ValidityStateFlags</dfn> {
   <div w-nodev>
 
   <p>The <dfn><code data-x="dom-ElementInternals-setFormValue">setFormValue(<var>value</var>,
-  <var>state</var>)</code></dfn> method of the <code>ElementInternals</code> interface must
-  run the following steps:</p>
+  <var>state</var>)</code></dfn> method steps are:</p>
 
   <ol>
-   <li><p>Let <var>element</var> be this <code>ElementInternals</code>'s <span
-   data-x="internals-target">target element</span>.</p></li>
+   <li><p>Let <var>element</var> be <span>this</span>'s <span data-x="internals-target">target
+   element</span>.</p></li>
 
    <li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
    <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
@@ -67577,12 +67586,11 @@ dictionary <dfn>ValidityStateFlags</dfn> {
   <dfn data-x="face-validation-anchor">validation anchor</dfn> element. It is null initially.</p>
 
   <p>The <dfn><code data-x="dom-ElementInternals-setValidity">setValidity(<var>flags</var>,
-  <var>message</var>, <var>anchor</var>)</code></dfn> method of the <code>ElementInternals</code>
-  interface must run the following steps:</p>
+  <var>message</var>, <var>anchor</var>)</code></dfn> method steps are:</p>
 
   <ol>
-   <li><p>Let <var>element</var> be this <code>ElementInternals</code>'s <span
-   data-x="internals-target">target element</span>.</p></li>
+   <li><p>Let <var>element</var> be <span>this</span>'s <span data-x="internals-target">target
+   element</span>.</p></li>
 
    <li><p>If <var>element</var> is not a <span>form-associated custom element</span>, then throw a
    <span>"<code>NotSupportedError</code>"</span> <code>DOMException</code>.</p></li>
@@ -67611,13 +67619,12 @@ dictionary <dfn>ValidityStateFlags</dfn> {
   </ol>
 
   <p>The <dfn><code data-x="dom-ElementInternals-validationMessage">validationMessage</code></dfn>
-  attribute of <code>ElementInternals</code> interface, on getting, must return the
-  <span data-x="face-validation-message">validation message</span> of this
-  <code>ElementInternals</code>'s <span data-x="internals-target">target element</span>.</p>
+  getter steps are to return the <span data-x="face-validation-message">validation message</span> of
+  <span>this</span>'s <span data-x="internals-target">target element</span>.</p>
 
-  <p>When <dfn data-x="face-entry-construction">entry construction algorithm</dfn> for a
-  <span>form-associated custom element</span> is invoked, given an element <var>element</var> and a
-  list <var>entry list</var>, run the following steps:</p>
+  <p>The <dfn data-x="face-entry-construction">entry construction algorithm</dfn> for a
+  <span>form-associated custom element</span>, given an element <var>element</var> and a
+  list <var>entry list</var>, consists of the following steps:</p>
 
   <ol>
    <li>
@@ -67647,7 +67654,20 @@ dictionary <dfn>ValidityStateFlags</dfn> {
 
   </div>
 
-  <hr>
+  <h5>Accessibility semantics</h5>
+
+  <dl class="domintro">
+   <dt><var>internals</var> . <code data-x=""><a href="#dom-ElementInternals-accessibility-idl-get">role</a></code> [ = <var>value</var> ]</dt>
+   <dd><p>Sets or retrieves the default ARIA role for <var>internals</var>'s <span
+   data-x="internals-target">target element</span>, which will be used unless the page author
+   overrides it using the <code data-x="attr-aria-role">role</code> attribute.</p></dd>
+
+   <dt><var>internals</var> . <code data-x=""><a href="#dom-ElementInternals-accessibility-idl-get">aria*</a></code> [ = <var>value</var> ]</dt>
+   <dd><p>Sets or retrieves various default ARIA states or property values for
+   <var>internals</var>'s <span data-x="internals-target">target element</span>, which will be used
+   unless the page author overrides them using the <code data-x="attr-aria-*">aria-*</code>
+   attributes.</p></dd>
+  </dl>
 
   <p w-nohtml>By using the <code data-x="">role</code> and <code data-x="">aria*</code> properties
   of <code>ElementInternals</code>, custom element authors can set default accessibile roles,