Move defineElement elsewhere?

[domenic]

Given the variety of proposals for new custom element related methods that are starting to fly around (e.g. #419 and #427 talk about upgrade-related helpers, plus there's always our plans for a registry API #154), we should start considering changes to the top-level API shape, and decide on something ASAP.

I can imagine three possibilities:

1. document.customElements.define. Everything goes on that object. document.customElements is null for documents without a browsing context.
2. HTMLElement.define. This makes it a bit clearer things are tied to the browsing context instead of the document. Other things can go there too. Right now the only things on there are a bunch of Node SHOUTY_CONSTANTS.
3. Punt on the problem: stick with document.defineElement, and just be sure to block future proposals on accepting one of the above two, at which point document.defineElement becomes an alias for one of those. This might not be feasible depending on how Custom elements disconnected from a document should not be upgraded #419 goes.

@annevk @rniwa @travisleithead thoughts?

[annevk]

window.nodeRegistry.defineElement()? I'm not sure why we'd hang it off document. I don't think putting it on HTMLElement is future-proof. And we might introduce other custom nodes in the future, maybe?

[domenic]

I don't think we're going to generalize this to arbitrary node types :). But yeah, we might allow custom SVG or MathML elements, and I suppose making people decide between SVGElement.define and HTMLElement.define would be bad?

window.customElements seems OK I guess.

[rniwa]

Or window.customElementDefinitions since window.customElements sounds like a list that contains instances of custom elements.

[domenic]

I think in context it's fine. window.customElements.define('...') etc.

[JanMiksovsky]

FWIW, I've occasionally wished for a way to know what custom elements have been registered.

• When debugging a complex component-based app with multiple levels of module dependencies and other complications, it can be helpful to just get confirmation that a particular custom element has, in fact, being successfully registered.
• I've already hit cases where I wanted to provide a definition for a component if a definition hadn't already been registered. It's possible to just call createElement('foo-bar') and sniff the result, but it'd be nice to have a more deterministic way.
• Someday I'd like the debugger to be able list the currently-registered elements, let me jump to their declarations, etc.

While @rniwa didn't intend to suggest a feature, I actually think having window.customElements provide a list of registered elements would be pretty interesting. It could be a dictionary or Map of element names to classes, for example.

class FooBar extends HTMLElement {...}
window.customElements.define('foo-bar', FooBar);
window.customElements['foo-bar'] // returns FooBar

Note that there's no potential for conflict between the element registration methods and custom element names, since the element names have to include a hyphen.

[domenic]

We definitely wouldn't use own properties, but a .get('name') API (plus perhaps more of the map-like friends like iterator) is reasonable.

[domenic]

This is now implemented (window.customElements): https://w3c.github.io/webcomponents/spec/custom/#custom-elements-api

Any proposals for new APIs to put on this should be a new issue. I support a .get().

[rianby64]

Hello! I'm reading this standard and found that still you're mentioning defineElement as main function for registering elements. Could you please tell me where can I update the documentation ? Thanks a lot in advance!

[domenic]

Thanks, I forgot to update the examples. Can do. The spec itself is updated though (those introduction sections are non normative).