Provide a mechanism to prevent or coalesce upgrades when defining new custom elements

[rniwa]

From #710, we should provide a mechanism to prevent automatic upgrades when defining a new custom element so that we'll end up with more predictable upgrading order & avoid O(nk) runtime cost of iterating over n DOM nodes for k custom elements.

[justinfagnani]

In previous scoped custom element registry proposals we briefly had a batch definition API, like:

customElements.defineMultiple({
  'my-element-1': MyElement1,
  'my-element-2': MyElement2,
});

That clearly allows for batching, but might not be general enough if there's not a single point where definitions can be made as is typical for using the current global registry. It might be sufficient for scoped registries though.

A disable/enable API might work:

customElements.disableUpgrades();
// ...
customElements.enableUpgrades();

Though due to module import ordering, disabling will need to happen before importing self-registering elements, so using it won't always be so straight-forward:

import './disable-upgrades.js';
import './app.js';
customElements.enableUpgrades();

[GeorgeTailor]

Maybe it would make sense to extend existing define method with an additional field in options param?

As an user we would provide a hint to the browser that we would like to upgrade a batch of custom elements manually later by passing upgrade: false to define method:

customElements.define('my-element-1', MyElement1, { upgrade: false });
...
customElements.define('my-element-2', MyElement2, { upgrade: false });

After that when the custom elements module(s) are imported, parsed and executed, we would call upgrade on elements that we need:

import './my-element-1.js';
import './my-element-2.js';
customElements.upgradeMultiple(['my-element-1', 'my-element-2']); // not sure what should be the argument here