HTML spec: section 4.11.1, for <details>
(HTMLDetailsElement
), should probably briefly but explicitly state that the element uses shadow DOM, and should probably link to section 15.5.5 to direct readers to further information
#10610
Labels
What is the issue with the HTML Standard?
BLUF: I think it'd be a good idea to amend the HTML standard section 4.11.1 so that it links to section 15.5.5 while summarizing the most important facts from 15.5.5 in brief.
The HTML spec defines the
details
element as using the shadow DOM, but only in 15.5.5: Thedetails
andsummary
elements. There is no explicit mention of the shadow DOM in 4.11.1: Thedetails
element, nor is there a link from 4.11.1 to 15.5.5. Someone who goes directly to the spec to look for information on thedetails
element is unlikely to find the mentions of the shadow DOM, because:details
element, in a spec that has a dedicated section for every element, is the dedicated section for thedetails
element.details
element will contain or otherwise direct a reader to all pertinent information about thedetails
element. It is therefore also reasonable to immediately stop looking for information upon finding that section.details
element is higher on the table of contents. Ctrl + F will find that section first, and if you want to get to 15.5.5's entry in the table of contents, you have to scroll (on my desktop) 32,711 pixels down the page, almost to the bottom.Moreover, someone who doesn't stumble upon 15.5.5 won't expect
details
to use the shadow DOM because there... doesn't seem to be any real reason for it to? Like, thinking about this like someone who isn't a browser engineer, "box what hides the things you put in it" shouldn't require a shadow DOM for the same reason "button that looks like an OS-native widget by default in most browsers" shouldn't require a shadow DOM. It feels like it should be sufficient for the spec to just say, "The disclosure widget hides stuff until the user clicks a thing. The button widget looks and acts like a button. Do whatever you have to do outside the realm of HTML, CSS, and the DOM to make that happen, vendors." It's baffling and unintuitive that a native element built into the browser is made of the same stuff that randoms like me scribble into Notepad++. All of this is to say that the Venn diagram of "people who haven't read or heard about section 15.5.5" and "people who would never in their lives guess thatdetails
was implemented using the shadow DOM" is a circle.Why this matters
The use of slots and the shadow DOM for the
details
element causes a number of quirks for web content, including by breaking CSS'sinherit
keyword. It's important to know when you're dealing with a shadow DOM, and since the shadow DOM is usually opt-in,details
is pretty egregious.CSSWG #8184 is an example from a couple years ago, and the thing that led me to file this issue after I found it while searching for something else. I've put together a demonstration of the reported issue here if anyone needs a visual reference. The issue report is also instructive, in my opinion, for how it actually played out. OP saw the shadow DOM quirks on
details
and, failing to understand what was going on, they reported it to Mozilla as a browser bug; a Firefox dev then directed OP to 15.5.5 to justify aRESOLVED INVALID
response. OP then submits an issue to CSSWG pointing out that this behavior is unintuitive even knowing the shadow DOM is involved; and even despite linking to their Bugzilla report as context, and suggesting changes to the spec that would entail treatingdetails
like a special case, the responses they get from folks involved in the standardization process were, to my eyes, at least, worded as though the confusion came entirely from the shadow DOM itself having the limits that it did, and not from the fact ofdetails
even using a shadow DOM to begin with -- as if it's obvious to everyone thatdetails
uses the shadow DOM and obvious why it should.Recommended solution
The dedicated section for the
details
element should call out the use of the shadow DOM, and then invite readers to jump to 15.5.5 to learn more about thedetails
shadow DOM setup in specific.Footnotes
On the one hand, WHATWG isn't responsible for what MDN does or doesn't link to. On the other hand, the "H" in "HTML" literally refers to a document system wherein one can follow links between pages -- and possibly arrive right in the middle of a large collection of information, out of context, without ever having seen that collection's table of contents or other primary navigation. If any document should be designed to withstand that, it should be the HTML standard. (And to the standard's credit, it largely is. The ability to click on a term's definition and see inbound links from the rest of the spec -- the extent to which navigation is baked right into the content -- is impressive.2) ↩
Of course, this also works against the spec. The specs are so massive, and formatted and themed so similarly, that when clicking on links to defined terms it's very easy to fail to notice when you've traveled to a completely different spec. There, if you click on a definition to see inbound links -- perhaps a definition that you just followed an inbound link to specifically so you could view the other inbound links -- you'll only see links from within the same spec, and not cross-spec links. In this way, the inbound link feature can actually offer something like a false sense of security: you think you can navigate more reliably than is actually possible. Sometimes there really is no better substitute for just saying, "Hey, this thing does the thing. Click here to learn more," inline in the text. ↩
The text was updated successfully, but these errors were encountered: