Re: [w3ctag/design-reviews] DOM (#229)

The DOM spec is the bedrock of the web platform. Architecturally it is quite sound and well-established (and even if there were major problems, it would be impossible to make significant changes). @annevk and friends have been keeping this living standard current as well as adding the occasional feature, integrating with other specs and concepts (e.g., Shadow DOM, new Event options, etc.). Our review glosses over some of the low-level algorithmic details assuming they “work”, or implementers will have pointed out bugs. Instead we tried to take a high-level look at understanding concepts as if we were newly introduced to the DOM and reading this document for the first time. Here are some of our notes.

**Mixing of the “old” and “new”.** For a new reader who wants to know what to actually use, the spec interleaves a bunch of new (good practice) APIs and old (compatibility purposes) APIs with the same functionality. For example, the `CustomEvent` constructor and `initCustomEvent()`. It could be helpful to more thoughtfully separate the old from the new to make the spec more useful as a reference. (Maybe even annotations as a second view?)

We noted that one approach that could help is having a WebIDL annotation for deprecated APIs present in the IDL, e.g., some kind of [Deprecated] extended attribute.

**Lack of “what is this (conceptually)” explainers.** Different DOM primitive interfaces do not provide a useful definition and do not provide the reader with helpful information on what is different from the other (not necessarily has to be normative) - e.g. couldn't figure out what a "ProcessingInstruction" is.

**NamedNodeMap.** Ah yes. It took some doing, but we eventually discovered that it’s possible to iterate over the `NamedNodeMap` using for..of, but we had to discover this through an obscure part of WebIDL. Would be nice if this could be made more obvious? E.g., an @@iterator directive..

**Composed Events.** We didn’t see a great explanation for how this was supposed to work. A diagram or short explanation would have been helpful. ([This was helpful.](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed))

**Still-used mailing list?** Section 2.8. recommends public-script-coord@w3.org as a place to have a discussion about adding new Events - but that list seems to be dead. Probably it could point to a better home for the discussion?

**AbortController.** AbortController sticks out like a sore thumb. Does this really belong here? Wondering if this is going to be the final design, or if the [TC39 proposal](https://github.com/tc39/proposal-cancelable-promises) is still being developed?

**Time to spec Mutation Events?** MutationEvents note in the intro says: “The old model is expected to be removed from implementations in due course. ”. I wonder if this is still true? E.g., are there signs that this is actually going to happen? Maybe it these events (the interoperable set) should finally be officially adopted into the DOM spec? One implementer (Mozilla?) was considering implementing these [MutationEvents] using the custom element’s nano-task concept for improved reliability and predictability. If this is web compatible, it would great to have it well-documented in DOM, rather than ignored.

**Callout to related issue?** “In the future we could allow custom get the parent algorithms.” - may want to reference issue https://github.com/whatwg/dom/issues/583 if interested readers would like to add additional comments.

**Explain attachShadow limited elements?** AttachShadow description lists elements that are allowed to have Shadow Roots attached. A short explanation of the principal as to why these elements would be useful.

**Improved wording?** Term: `// useless;` is used a few places in the IDLs… Perhaps a better word like “historical” or “fixed/static value” or “value never changes” would be a less-negative phrase.

**Goodbye TreeWalker?** TreeWalker seems like a pretty useless feature. Sorry, “historical”. (Chrome status shows essentially zero usage :)

**Let’s continue to invest in DOM.** The issues list seem to have a bunch of nice ideas that could potentially be looked into. Some of the DOM’s limited feature set seem to have resulted in strange shortcuts on the web (e.g., `innerHTML`) which should have been originally possible with DOM, but was not particularly nice to do so. Time to make this nicer?

-Travis and @cynthia
👍😁🐱‍🏍



-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/design-reviews/issues/229#issuecomment-424390065