Add authoring guidance for writing custom element constructors

[domenic]

After #405 lands we should add some examples. Most importantly we should add some authoring requirements for writing constructors, that is, "must"s and "should"s aimed at authors. So far I can think of:

• Authors must include a parameter-less super() call as the first statement in their constructor
• Authors must not use return override
• Authors should not inspect the DOM or perform any interesting operations (such as fetching a resource) during construction; this should be delayed until attachedCallback [or whatever attachedCallback gets renamed to]. This includes inspecting their own children or attributes (the latter of which can be handled by attributeChangedCallback).
• Authors should use the constructor to set up initial state with default values.

[sideshowbarker]

I think it’d be better for the actual language to end up being “Documents must/should” rather than Authors—though I realize many or most of the existing precedents in the spec use Authors.

[annevk]

That or just "developers", which is how they prefer to be called.

[sideshowbarker]

Well part of my point is that when it comes to, say, doing things like actual testing of requirements, you can’t test authors (or developers) against requirements—at least not directly—but you can test documents directly against requirements.

It may seem like caring about the difference is sorta just splitting hairs—since I guess you can just consider any documents conceptually to be something that some author/developer produced, so the requirements are the same, just expressed with a level of indirection. But really, the point of the spec is to be precise, and IMHO for these requirements, to be precise it’s necessary to use language that considers the documents in isolation from whoever the authors/developers are that produced them.

[JanMiksovsky]

Regarding doing work in an attachedCallback: if an element is removed and then re-inserted, it's my understanding that the attachedCallback will run again. If that's the case, you may want to clarify that any one time initialization in the attachedCallback needs to be explicitly set up that way.

E.g., we have components that, in their createdCallback, add event listeners to the host or an element in their shadow subtree). It sounds like we should move most of that code to attachedCallback — but we only want to wire up the event listeners once. That suggests creating a private flag to keep track of whether we've already done this one-time initialization work so that, in the event the element is detached and then later reattached, we don't inadvertently perform that initialization again.

If I've got that right, would that be worth documenting? It seems likely that people will fail to account for the reattachment scenario. I also want to make sure we document best practices for the "Reattachment" item in the Gold Standard checklist for web components.

[domenic]

Good catch. However, I think event listeners are probably a reasonable thing to put in your constructor, so I'll be sure to mention that explicitly, as well as the guard.

[JanMiksovsky]

Great, thanks.

[jessetane]

From section 2.2:

The element must not gain any attributes or children, as this violates the expectations of consumers who use the createElement or createElementNS methods.

As @JanMiksovsky pointed out, elements that create their own subtree would need to use a private flag / conditional in the connectedCallback which is a potential footgun and imo sort of messy looking. Would setting innerHTML or calling appendChild in a constructor throw an error? Is there a technical reason for this limitation? The one given is that it "violates expectations" but I'm unclear on what those expectations are - can anyone elaborate?

[domenic]

would need to use a private flag / conditional in the connectedCallback

Yes, they would. This should be something done very rarely anyway, so making it inconvenient to do so is not a real concern.

Would setting innerHTML or calling appendChild in a constructor throw an error?

Yes, or more precisely, it would cause element creation to fail, so createElement or the parser or whatever would fail to create the element.

The one given is that it "violates expectations" but I'm unclear on what those expectations are - can anyone elaborate?

So far in the history of the DOM, every element ever returned from createElement has had no attributes and no children. The expectation is that this invariant can be relied on going forward.