Add `customElements.upgrade`

[rniwa]

We need a mechanism to trigger an upgrade on a disconnected tree of nodes per in-persion discussions with @domenic and @justinfagnani

[rniwa]

Also see #419 (comment)

[justinfagnani]

Additional thought:

If we get something like CustomElementRegistry#upgrade(rootNode), would it be interesting to think about a way to block automatic upgrade of a tree due to registrations? The motivation is when you know you're about to define a large number of elements and want to do upgrading in a single batch for performance.

We've had various requests for controlling upgrades come in from customers, but @sorvell would have more detail.

[domenic]

Argh, let's not scope-creep this, or it won't happen :(. We already have to figure out deep vs. not...

[rniwa]

I think deep makes more sense than shallow. It's almost never useful to upgrade just the root and not its descendent.

[bkardell]

Is there actually a use case for shallow even?

[snuggs]

@bkardell @rniwa is there any way you can provide a code sample of shallow vs deep?
In our implementation to "upgrade" is merely prototype swizzling and dispatching connectedCallback(). A subset of the entire spec but suits our minimalistic needs.

https://github.com/devpunks/snuggsi/blob/master/custom-element-registry/index.es#L30-L45

Just trying to understand if you mean the following:

<foo-bar>
  <baz-bat>Who is responsible for my upgrade?</baz-bat>
</foo-bar>

[annevk]

@snuggs the method is given a node. The question is then whether you just upgrade that node, or that node and also all its descendants. So with your example, if you pass in foo-bar, is baz-bat upgraded or not?

[snuggs]

@annevk Thanks for the clarity! Ran into this use case with a client. The use case was foo-bar definition blocking head. while baz-bat was defered in definition. Wound up causing strange race conditions with the upgrade process. We settled on covering all mutually exclusive positions:

1. parent defined before child.
2. child defined before parent.

What worked was wherever the script is declared (pre/post body) the algo is this:

1. Collect all custom elements up to point and upgrade.
2. (Always) upgrade upon DOM insertion of a custom element.
3. Whether upgrade is successful or not fails silently and doesn't throw to the call site.

3 is where the specs would usually 💥 but we were more lackadaisical.

To be clear this isn't an encouragement towards the spec. More trying to abide with implementation aligned as close to what we are doing here while underlying vendor implementation evolves.

Super looking forward to movement in this space. Many of these problems have been solving for the past year or two. Love seeing this be revisited.