search

mdn / content

The content behind MDN Web Docs
https://developer.mozilla.org
Other
9.13k stars 22.45k forks source link

CustomElementRegistry needs updating #6617

Open rachelandrew opened 3 years ago

rachelandrew commented 3 years ago

I've been documenting ElementInternals, in the process of this I think that the documentation we have for custom elements may need some updating. In particular I noticed that https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry includes no information about the disable internals, or disable shadow booleans.

https://html.spec.whatwg.org/multipage/custom-elements.html#concept-custom-element-definition-disable-internals

I think it would probably be worth someone taking a look at this content and seeing what else needs updating.

Once updated it would be good to link this to the information about attachInternals in /Web/API/Element/attachInternals

bsmth commented 2 months ago

@hamishwillee you had a significant update in https://github.com/mdn/content/pull/30566, does that PR resolve this issue or are there still gaps in your opinion?

hamishwillee commented 2 months ago

I did not touch this. I'd need to do a fair bit of work to understand if the solution/work indicated is needed, but I can see that some work is needed for sure.

What I do know ...

So the linked HTML spec talks about booleans disableInternals and internals that are part of a custom element. There is no mention of these anywhere in MDN. That is because, as far as I can tell, they exist but are not in any defined interface.

What is documented is that in Element.attachShadow() example disabling shadow dom, you can declare a disabledFeatures static variable in your custom element and list shadow. If you try and attach a shadow the method will throw if the custom element. Looking into the spec, the existence of this disabledFeatures and the term "shadow" creates this boolean.

Similarly, you can specify "internals" in disabledFeatures to prevent internals being added, though I do not know what implications that actually has, and this is not documented in HTMLElement.attachInternals()

So what I'd say is that disabledFeatures needs to be documented as part of the guide for custom elements - it is much a part of them as the callbacks. It also needs an example like the one in attachShadow() in attachInternal(). Both those sections need an explanation of why this might be done.

The specific suggestion to add info about this to CustomElementRegistry might not be the right place - depends on where the failure point is - if this shows up when you register a custom element, then yes, it would make sense to have that information here.