Custom elements: Add element.attachInternals() and ElementInternals i…

…nterface

This fixes WICG/webcomponents#758

source

@@ -10195,6 +10195,8 @@ interface <dfn>HTMLElement</dfn> : <span>Element</span> {
   [<span>CEReactions</span>] attribute DOMString <span data-x="dom-autocapitalize">autocapitalize</span>;
 
   [<span>CEReactions</span>] attribute [TreatNullAs=EmptyString] DOMString <span data-x="dom-innerText">innerText</span>;
+
+  <span>ElementInternals</span> <span data-x="dom-attachInternals">attachInternals</span>();
 };
 
 <span>HTMLElement</span> includes <span>GlobalEventHandlers</span>;
@@ -66612,6 +66614,10 @@ document.body.append(parent);
    href="#html-element-constructors">HTML element constructors</a>. Each entry in the list will be
    either an element or an <dfn data-x="concept-already-constructed-marker"><i>already
    constructed</i> marker</dfn>.</dd>
+
+   <dt>A <dfn data-x="concept-custom-element-definition-disable-internals">disable
+   internals</dfn></dt>
+   <dd>A boolean that controls <code data-x="dom-attachInternals">attachInternals()</code>.
   </dl>
 
   <p>To <dfn data-export="">look up a custom element definition</dfn>, given a <var>document</var>,
@@ -66834,6 +66840,21 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
        <code data-x="">sequence&lt;DOMString></code>. Rethrow any exceptions from the
        conversion.</p></li>
       </ol>
+
+     <li><p>Let <var>disableInternals</var> be false.
+
+     <li><p>Let <var>disabledFeatures</var> be
+     <span data-x="js-Get">Get</span>(<var>constructor</var>, "disabledFeatures").  Rethrow any
+     exceptions.</p></li>
+
+     <li><p>If <var>disabledFeatures</var> is not undefined, then set
+     <var>disabledFeaturesSequence</var> to the result of
+     <span data-x="concept-idl-convert">converting</span> <var>disabledFeatures</var> to a
+     <code data-x="">sequence&lt;DOMString></code>.  Rethrow any exceptions from the
+     conversion.</p></li>
+
+     <li><p>Set <var>disableInternals</var> to true if <var>disabledFeaturesSequence</var> contains
+     <code data-x="">"internals"</code>.</p></li>
     </ol>
 
     <p>Then, perform the following substep, regardless of whether the above steps threw an exception
@@ -66854,9 +66875,11 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
    <span data-x="concept-custom-element-definition-constructor">constructor</span>
    <var>constructor</var>, <span
    data-x="concept-custom-element-definition-observed-attributes">observed attributes</span>
-   <var>observedAttributes</var>, and <span
+   <var>observedAttributes</var>, <span
    data-x="concept-custom-element-definition-lifecycle-callbacks">lifecycle callbacks</span>
-   <var>lifecycleCallbacks</var>.</p></li>
+   <var>lifecycleCallbacks</var>, and <span
+   data-x="concept-custom-element-definition-disable-internals">disable internals</span>
+   <var>disableInternals</var>.</p></li>
 
    <li><p>Add <var>definition</var> to this <code>CustomElementRegistry</code>.</p></li>
 
@@ -67429,6 +67452,49 @@ customElements.define("x-foo", class extends HTMLElement {
 
   </div>
 
+  <h4>The <code>ElementInternals</code> interface</h4>
+
+  <p>Each <code>ElementInternals</code> has a <dfn data-x="internals-target">target element</dfn>,
+  which is a custom element.  <code>ElementInternals</code> provides various operations and
+  attributes to communicate with UA in order to implement custom elements with features which need
+  UA's assist.</p>
+
+  <pre><code class="idl" data-x="">[Exposed=Window]
+interface <dfn>ElementInternals</dfn> {
+  <!-- We'll add some stuff here -->
+};</code></pre>
+
+  <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>
+   <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>InvalidStateError</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>InvalidStateError</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 new <span>ElementInternals</span> instances
+   <span data-x="internals-target">targeting</span> <var>element</var>, and return it.</p></li>
+  </ol>
 
   <h3 split-filename="semantics-other" id="common-idioms">Common idioms without dedicated elements</h3>