Add customElements.upgrade()

Closes WICG/webcomponents#710.

Author: domenic

source

@@ -3147,7 +3147,9 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-order">tree order</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-tree-order">shadow-including tree order</dfn> concepts</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-child" data-x="concept-tree-child">child</dfn> concept</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-root">root</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-root">shadow-including root</dfn> concepts</li>
-     <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-descendant">shadow-including descendant</dfn> concepts</li>
+     <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</dfn>,
+             <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-descendant">shadow-including descendant</dfn>, and
+             <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-inclusive-descendant">shadow-including inclusive descendant</dfn> concepts</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-first-child">first child</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-next-sibling">next sibling</dfn> concepts</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#document-element">document element</dfn> concept</li>
      <li>The <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document">in a document</dfn> (legacy), and <dfn data-x-href="https://dom.spec.whatwg.org/#connected">connected</dfn> concepts</li>
@@ -66186,6 +66188,7 @@ interface <dfn>CustomElementRegistry</dfn> {
   [<span>CEReactions</span>] void <span data-x="dom-CustomElementRegistry-define">define</span>(DOMString name, Function constructor, optional ElementDefinitionOptions options);
   any <span data-x="dom-CustomElementRegistry-get">get</span>(DOMString name);
   Promise&lt;void&gt; <span data-x="dom-CustomElementRegistry-whenDefined">whenDefined</span>(DOMString name);
+  [<span>CEReactions</span>] void <span data-x="dom-CustomElementRegistry-upgrade">upgrade</span>(<span>Node</span> root);
 };
 
 dictionary <dfn>ElementDefinitionOptions</dfn> {
@@ -66243,6 +66246,13 @@ dictionary <dfn>ElementDefinitionOptions</dfn> {
    promise will be immediately fulfilled.) Returns a promise rejected with a
    <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if not given a <span>valid
    custom element name</span>.</dd>
+
+   <dt><var>window</var> . <code data-x="dom-window-customElements">customElements</code> . <code
+   subdfn data-x="dom-CustomElementRegistry-upgrade">upgrade</code>(<var>root</var>)</dt>
+
+   <dd><span data-x="concept-try-upgrade">Tries to upgrade</span> all <span>shadow-including
+   inclusive descendant</span> elements of <var>root</var>, even if they are not
+   <span>connected</span>.</dd>
   </dl>
 
   <p><dfn>Element definition</dfn> is a process of adding a <span>custom element definition</span>
@@ -66462,6 +66472,35 @@ fetch(articleURL)
   });</pre>
   </div>
 
+  <p>When invoked, the <dfn><code
+  data-x="dom-CustomElementRegistry-upgrade">upgrade(<var>root</var>)</code></dfn> method must run
+  these steps:</p>
+
+  <ol>
+   <li><p>Let <var>candidates</var> be a <span>list</span> of all of <var>root</var>'s
+   <span>shadow-including inclusive descendant</span> elements, in <span>tree order</span>.</p></li>
+
+   <li><p><span data-x="list iterate">For each</span> <var>candidate</var> of <var>candidates</var>,
+   <span data-x="concept-try-upgrade">try to upgrade</span> <var>candidate</var>.</p></li>
+  </ol>
+
+  <div class="example">
+   <p>The <code data-x="dom-CustomElementRegistry-upgrade">upgrade()</code> method allows upgrading
+   of elements at will. Normally elements are automatically upgraded when they become
+   <span>connected</span>, but this method can be used if you need to upgrade before you're ready to
+   connect the element.</p>
+
+   <pre>const el = document.createElement("spider-man");
+
+class SpiderMan extends HTMLElement {}
+customElements.define("spider-man", SpiderMan);
+
+console.assert(!(el instanceof SpiderMan)); // not yet upgraded
+
+customElements.upgrade(el);
+console.assert(el instanceof SpiderMan);    // upgraded!</pre>
+  </div>
+
   <h4><dfn data-x="custom-element-upgrades">Upgrades</dfn></h4>
 
   <p>To <dfn data-x="concept-upgrade-an-element" data-export="">upgrade an element</dfn>, given as