Clean up HTML <-> DOM hooks

[domenic]

What is the issue with the HTML Standard?

Previous discussions: #2771, #7712, #10259.

DOM and HTML have various "hooks" for how they interface. They aren't always formalized the same way. But the basic ones are:

• attribute change steps
• removing steps: node is removed from a parent
• insertion steps: node is inserted into a parent
• cloning steps
• children changed steps
• adopting steps
• HTML element insertion steps: per-element specialization of insertion steps, used inconsistently
• HTML element removing steps: per-element specialization of removing steps, used inconsistently
• a node is inserted into a document, becomes connected, becomes browsing-context connected: specializations of insertion steps that only runs under some conditions
• a node is removed from a document, becomes disconnected, becomes browsing-context disconnected: specializations of removing steps that only runs under some conditions

This setup is messy in various ways:

• The relative order of various steps is not clear. (In practice this is rarely a problem, but there might be some cases where it's observable.)
• "inserted into a document" / "removed from a document" are sometimes used incorrectly when "becomes connected" / "becomes disconnected" is desired, because the former are leftover from a pre-shadow DOM world.
• There is a lot of inverted control, especially around the "becomes X", where instead of clear algorithms we say things like "the Y algorithm must run when the element becomes connected". (Example, example, ...). (This is probably the most annoying thing to fix.)
• The DOM <-> HTML layering is not extremely clear. For example, DOM provides "removing steps", and HTML defines its removing steps, but "a node is removed from a document" / "becomes disconnected" / "becomes browsing-context disconnected" are only implicitly wired up to the removing steps.
• It's not obvious when writing the spec for an element whether to define something in HTML element removal steps vs. the other three HTML specializations.
• The naming is inconsistent; mostly things end with "steps" but not always.
• It's inconsistent when writing these algorithms whether to include the parameter names.
• In practice I don't think specs besides HTML, SVG, and MathML should be adding hooks here, so DOM's genericness is not helpful.

Here is what I think an ideal setup would look like. I've separated it into workstreams which could be pursued mostly-independently.

• Cleanup DOM itself
  • Remove the attribute change steps defined in DOM for ID and just define ID as a "getter".
  • Inline all other attribute change steps defined in DOM, into the actual point of changing the attribute.
• Cleanup DOM <-> other specs interface
  • Define "HTML Standard insertion steps", "HTML Standard removing steps", etc. as centralized algorithms defined in HTML. DOM can call them.
  • Do the same for SVG and MathML.
• Clean up HTML insertion/removing
  • Consolidate all insertion/removing things defined in HTML into either the "HTML Standard insertion steps" or the per-local-name "HTML element insertion steps". (Clarify what happens when setting rel content attribute on link element #8138 (comment) is part of this.) Do manual checks for "in a document tree" or "connected" or "browsing-context connected" as necessary.
  • Make sure "HTML Standard insertion steps" and "HTML element insertion steps" have clearly-defined parameters, and that all declaration sites properly include all those parameters. (easy, could be done now)
  • Survey cases of "inserted into a document" / "removed from a document" to see if they're properly shadow DOM aware. This may involve writing WPTs.
• Clean up HTML attribute changes
  • Consolidate all attribute change steps defined in HTML into central "HTML Standard attribute change steps".
  • These can call out to other named algorithms, e.g. event handler synchronization can be defined as something like a "synchronize event handlers" algorithm.
  • Potentially consider creating per-attribute-local-name "HTML attribute change steps" which we can dispatch too. Or per-element-local-name? Dispatching on both would probably be too complicated.
• Clean up other HTML hooks, i.e. cloning, children changed, and adopting, by centralizing them into single "HTML Standard cloning steps" etc. I don't think per-element is really necessary since there are so few of these.
• Check for any cases where multiple hooks can apply to a single mutation, and write WPTs for the ordering / ensure the spec reflects consensus ordering.

[annevk]

cc @domfarolino

[domfarolino]

This is great, thanks for filing this. FWIW I've added it to my curated list of "Medium-sized medium priority spec projects" which I haven't publicized too much but it's worth mentioning here maybe.