Specify the rendering of <details> in more detail. #10265

dbaron · 2024-04-09T16:14:34Z

This makes a number of related changes to specify the rendering of the <details> element:

It specifies the structure of the user agent shadow tree. This appears largely interoperable between implementations with the exception of the style or link element for the default summary styles: Gecko uses a link element as the first child, Chromium uses a style element as the last child, and WebKit does not use a style element (see below). This specifies a style or link as the last child with a note that the order is not observable.
It specifies the existence of the default summary and the presence of UA dependent text inside of it. This is present in all of Chromium, Gecko, and WebKit.
It specifies the styles needed for the default summary. These match Chromium and Gecko. (These are not present in WebKit because WebKit's mechanism for styling the marker does not match the existing spec; see bug 157323.)
It removes the restriction that <details> is a block and cannot be changed. This is prototyped in Chromium and Gecko. This fixes Don't force <details> to be a block. #9830.
It specifies that the summary element is display: block by default. This matches all of Chromium, Gecko, and WebKit.
It specifies which element matches the ::details-content pseudo-element. This is prototyped in Chromium.
It makes a potentially riskier change by making the slot element that matches ::details-content be display: block all the time (rather than only when closed). This is prototyped in Chromium (more recently than the other changes).

See w3c/csswg-drafts#9879 and w3c/csswg-drafts#9951 for more background.

At least two implementers are interested (and none opposed):
- Chromium support, see issue 40068507
- Gecko position pending: shown partial interest based on bug 1856374 but that's only a piece of this; remainder is covered by improved styling of <details> and <summary> elements mozilla/standards-positions#1027
- WebKit support: improved styling of <details> and <summary> elements WebKit/standards-positions#351
Tests are written and can be reviewed and commented upon at:
Implementation bugs are filed:
- Chromium: issue 40068507
- Gecko: bug 1901037
- WebKit: bug 275211
MDN issue is filed: document ::details-content pseudo-element and stylability of <details> element mdn/mdn#559
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

/infrastructure.html ( diff )
/rendering.html ( diff )

This makes a number of related changes to specify the rendering of the <details> element: * It specifies the structure of the user agent shadow tree. This appears largely interoperable between implementations with the exception of the style or link element for the default summary styles: Gecko uses a link element as the first child, Chromium uses a style element as the last child, and WebKit does not use a style element (see below). This specifies a style or link as the first child. * It specifies the existence of the default summary and the presence of UA dependent text inside of it. This is present in all of Chromium, Gecko, and WebKit. * It specifies the styles needed for the default summary. These match Chromium and Gecko. (These are not present in WebKit because WebKit's mechanism for styling the marker does not match the existing spec.) * It removes the restriction that <details> is a block and cannot be changed. This is prototyped in Chromium and Gecko. This fixes whatwg#9830. * It specifies that the summary element is display: block by default. This matches all of Chromium, Gecko, and WebKit. * It specifies which element matches the ::details-content pseudo-element. (TODO: This needs to be specified in CSS) This is prototyped in Chromium. See w3c/csswg-drafts#9879 and w3c/csswg-drafts#9951 for more background.

dbaron · 2024-04-09T16:15:40Z

Sorry, apparently Shift-enter submits the form, I wasn't quite ready to submit and I'll continue editing the above comment.

domenic · 2024-04-11T02:57:40Z

It specifies the structure of the user agent shadow tree. This appears largely interoperable between implementations with the exception of the style or link element for the default summary styles: Gecko uses a link element as the first child, Chromium uses a style element as the last child, and WebKit does not use a style element (see below). This specifies a style or link as the first child.

Are these differences observable? If not, then perhaps the spec can be clearer about that, so that people understand any implementation strategy that achieves equivalent results is fine.

dbaron · 2024-04-11T13:30:10Z

Are these differences observable? If not, then perhaps the spec can be clearer about that, so that people understand any implementation strategy that achieves equivalent results is fine.

That's a good question. When I wrote it I was (for some reason) thinking that the ordering was observable via selectors, but now that I think about it again I think it's not. We do need to get the exact CSS definitions of what does and doesn't apply sorted out, though, to make sure. But I think as long as (a) link or style in the shadow tree are display:none and can't be changed and (b) the relative positions of the elements in the shadow tree can't be determined by selectors, then I think it's not observable. (The relative positions of displayable elements in the shadow tree can be determined by layout differences, probably most easily with display: grid.)

annevk

Can we describe it as two child elements and an associated style sheet? It seems like it should be immaterial how the style sheet is associated with the shadow tree. It just needs to have one.

annevk · 2024-04-15T15:53:13Z

source

+    <p>The second child element is a <code>slot</code> that is expected to take the
+    <code>details</code> element's first <code>summary</code> element child, if any.  This element
+    has a single child <code>summary</code> element called the <dfn>default summary</dfn> which has
+    text content that is <span>implementation-defined</span> (and probably locale-specific).</p>


Should we recommend here that it follows from the node's language? I think that's what we do for form controls today even though it's not (yet) implemented?

This matches the current wording for the default text of submit/reset buttons and (except for "possibly" versus "probably") the text of the "Choose file" button in <input type=file>. The only wording I found that seems like what you're thinking of was the wording about presentation of dates, times, and numbers. This seems more similar to submit/reset and to the file chooser button than it it does to presentation of dates, in that it feels a bit odd to make this differ from those.

I suspect that when we changed the wording for dates, times, and numbers, the button language was overlooked. But I guess we can sort that out in a follow-up.

Filed #10437 to follow up.

annevk · 2024-04-15T15:55:03Z

source

+    <!-- TODO: link to CSS definition when spec is ready -->
+    <p>This element is expected to match the '::details-content' pseudo-element.</p>


Should this also be mentioned in HTML's Selectors section?

I'm not sure. The one existing pseudo-element (::file-selector-button) is not currently mentioned there. It seems like it might be useful to mention the pseudo-elements in that section, but it also seems like maybe (unlike for the pseudo-classes) if we do so, perhaps the pseudo-elements part of that section should be more like an index than the location of the formal definition?

Yeah, I guess that's correct. In which case maybe it's not worth it.

…o be the first child.

dbaron · 2024-04-18T20:07:13Z

Are these differences observable? If not, then perhaps the spec can be clearer about that, so that people understand any implementation strategy that achieves equivalent results is fine.

Can we describe it as two child elements and an associated style sheet? It seems like it should be immaterial how the style sheet is associated with the shadow tree. It just needs to have one.

I've revised the change to go mostly in this direction: I still describe the style as an element, explicitly note that the order isn't observable, and note that its association using an element isn't observable either (although I don't know what other standard mechanism we'd describe the styles with). I also now describe it as the third child rather than the first, since in hindsight it seems nice to use "first" and "second" for the first and second rendered children. But I didn't go so far as to just handwave about how the association is made. Does that seem reasonable?

domenic

Editorially LGTM. Happy to merge when we have the checkboxes filled out. Let us know if you have other people (e.g. @emilio) whose reviews you want to block on before merging.

emilio · 2024-04-22T06:13:54Z

I've revised the change to go mostly in this direction: I still describe the style as an element, explicitly note that the order isn't observable, and note that its association using an element isn't observable either (although I don't know what other standard mechanism we'd describe the styles with).

Adopted stylesheets would be an option fwiw.

I also now describe it as the third child rather than the first, since in hindsight it seems nice to use "first" and "second" for the first and second rendered children. But I didn't go so far as to just handwave about how the association is made. Does that seem reasonable?

Works for me.

emilio · 2024-04-22T13:45:28Z

source

+   <li>
+    <p>The third child element is either a <code>link</code> or <code>style</code>
+    element with the following styles for the <span>default summary</span>:</p>
+    <pre><code class="css">:host summary {


You can probably use :host > summary for parallelism with the rule below right? (or just summary?)

@dbaron, ping to make sure you saw this, as I agree it seems strange for these two lines to diverge.

Sorry for missing this. I've now made them consistent by changing the second selector, since that matches both Chrome's code and Firefox's code.

Awesome. Can you be sure this distinction is tested?

I think it's untestable, since it's styling the UA shadow DOM, and the only summary in that shadow DOM is in fact a child of the host.

(But when I was adjusting for consistency it seemed to make sense to match the existing implementations even when the difference didn't matter.)

Er, actually... maybe it's not a child of the host and the old style was just wrong!

Yeah it's not, because it's the slot fallback.

dbaron · 2024-06-03T18:15:35Z

One substantive thing that I'm thinking of changing here: right now the ::details-content is a pseudo-element that addresses an element that is internally a <slot>. <slot> elements default to display: contents. This is somewhat inconvenient since some styles don't work on elements that are display: contents. So I think probably it should be display: block by default all of the time (rather than only when it's hidden).

(This has tripped me up multiple times while writing examples, and I think it's probably better to change it if it doesn't break anything, which I don't think it will.)

bramus · 2024-06-03T20:06:50Z

I think probably it should be display: block by default all of the time (rather than only when it's hidden).

In all my experiments (here, here, and here) I have done this, so +1 on using display: block by default.

This simplifies the example in two ways: 1. By depending on the animation rules defined in https://drafts.csswg.org/css-contain-3/#content-visibility-animation the step-end and step-start values are not needed. (I had forgotten about these.) 2. By depending on the change in whatwg/html#10265 (comment) and whatwg/html@fb3033a the display: block is no longer needed.

dbaron · 2024-06-18T20:48:24Z

I think this is ready for another look. There are a few additional changes since the last round of reviews; the draft commit message above is updated to reflect them.

(There's one checkbox still unchecked, but that's just because I'm waiting to make a PR to make the tests not tentative until the last tentative test lands, hopefully later today or Thursday.)

1. By depending on the animation rules defined in https://drafts.csswg.org/css-contain-3/#content-visibility-animation the step-end and step-start values are not needed. 2. 2. By depending on the change in [whatwg/html#10265 (comment)](whatwg/html#10265 (comment)) and whatwg/html@fb3033a the display: block is no longer needed.

1. By depending on the animation rules defined in https://drafts.csswg.org/css-contain-3/#content-visibility-animation the step-end and step-start values are not needed. 2. 2. By depending on the change in whatwg/html#10265 (comment) and whatwg/html@fb3033a the `display: block` is no longer needed.

This removes the ".tentative" from the filename of tests that are testing the changes specified in whatwg/html#10265 and removes one test (testing that the display property is ignored) that is obsoleted by those changes. (A number of the other tests test what the display property does.)

1. By depending on the animation rules defined in https://drafts.csswg.org/css-contain-3/#content-visibility-animation the step-end and step-start values are not needed. 2. 2. By depending on the change in whatwg/html#10265 (comment) and whatwg/html@fb3033a the `display: block` is no longer needed.

domenic

LGTM, modulo last question about more tests.

It looks like since this last got a detailed look from @annevk and @emilio, we changed ::details-content to be display: block. (Is that tested too?)

So, I'll give them a few more days to chime in, and plan on merging this around Wednesday Japan time if nothing further comes in.

emilio

Yeah sounds good trying to make the slot display: block unconditionally.

emilio · 2024-06-21T16:20:21Z

source

+    <p>This element is expected to match the <span>'::details-content'</span> pseudo-element.</p>
+
+    <p>This element is expected to have its <code data-x="attr-style">style</code> attribute set to
+    "<code data-x="">display: block; content-visibility: hidden;</code>" when the


I think it'd be slightly nicer to make the display: block change part of the UA sheet. Maybe slot + slot { display: block }? Same with the content-visibility one for what is worth (we do this), but I guess it doesn't matter much and it's not really observable. It's just less magic

My inclination is that it is probably reasonable to do that as a separate change, but I'd prefer not to make this change bigger (this is an issue that already exists prior to this PR), and I'd probably also like to check it by implementing it and making sure it actually works the way we think it does.

Sure, sorry should've clarified that my comment wasn't meant to be blocking in any way. Sounds good. Maybe file a follow-up issue for this?

Filed #10438 to follow up.

) This removes the ".tentative" from the filename of tests that are testing the changes specified in whatwg/html#10265 and removes one test (testing that the display property is ignored) that is obsoleted by those changes. (A number of the other tests test what the display property does.)

… no longer be tentative., a=testonly Automatic update from web-platform-tests Make tests for new details styling rules no longer be tentative. (#46847) This removes the ".tentative" from the filename of tests that are testing the changes specified in whatwg/html#10265 and removes one test (testing that the display property is ignored) that is obsoleted by those changes. (A number of the other tests test what the display property does.) -- wpt-commits: fa175971884023f4012147551ca6fb187c8c417b wpt-pr: 46847

… no longer be tentative., a=testonly Automatic update from web-platform-tests Make tests for new details styling rules no longer be tentative. (#46847) This removes the ".tentative" from the filename of tests that are testing the changes specified in whatwg/html#10265 and removes one test (testing that the display property is ignored) that is obsoleted by those changes. (A number of the other tests test what the display property does.) -- wpt-commits: fa175971884023f4012147551ca6fb187c8c417b wpt-pr: 46847 UltraBlame original commit: 5cd2d3944f207a6f45e6be3222e018d674202e7b

… no longer be tentative., a=testonly Automatic update from web-platform-tests Make tests for new details styling rules no longer be tentative. (#46847) This removes the ".tentative" from the filename of tests that are testing the changes specified in whatwg/html#10265 and removes one test (testing that the display property is ignored) that is obsoleted by those changes. (A number of the other tests test what the display property does.) -- wpt-commits: fa175971884023f4012147551ca6fb187c8c417b wpt-pr: 46847

) This removes the ".tentative" from the filename of tests that are testing the changes specified in whatwg/html#10265 and removes one test (testing that the display property is ignored) that is obsoleted by those changes. (A number of the other tests test what the display property does.)

dbaron requested a review from emilio April 9, 2024 18:10

domenic added normative change topic: rendering labels Apr 11, 2024

annevk reviewed Apr 15, 2024

View reviewed changes

Be more flexible about the style mechanism rather than requiring it t…

9f67c86

…o be the first child.

domenic approved these changes Apr 22, 2024

View reviewed changes

emilio approved these changes Apr 22, 2024

View reviewed changes

emilio reviewed Apr 22, 2024

View reviewed changes

This was referenced May 14, 2024

Proposal for improvements to <details> styling openui/open-ui#744

Open

improved styling of <details> and <summary> elements mozilla/standards-positions#1027

Closed

dbaron mentioned this pull request May 22, 2024

improved styling of <details> and <summary> elements WebKit/standards-positions#351

Closed

Link ::details-content to definition in css-pseudo-4.

baead7f

dbaron mentioned this pull request Jun 5, 2024

improvements to <details> styling (widget structure) w3ctag/design-reviews#965

Closed

1 task

Retain display:block default on ::details-content when details is open.

fb3033a

dbaron mentioned this pull request Jun 17, 2024

document ::details-content pseudo-element and stylability of <details> element mdn/mdn#559

Open

1 task

yisibl mentioned this pull request Jun 20, 2024

[css-pseudo-4] Simplified example of ::details-content w3c/csswg-drafts#10476

Merged

Make selectors in shadow dom style sheet parallel each other.

4abf496

dbaron mentioned this pull request Jun 20, 2024

Make tests for new details styling rules no longer be tentative. web-platform-tests/wpt#46847

Merged

domenic approved these changes Jun 21, 2024

View reviewed changes

emilio approved these changes Jun 21, 2024

View reviewed changes

domenic merged commit e0e3b26 into whatwg:main Jun 26, 2024
2 checks passed

This was referenced Jun 26, 2024

should default reset/submit button text and default summary text use node's language rather than being locale-specific? #10437

Open

move style changes for opening/closing details into UA sheet rather than being style attribute manipulation #10438

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Specify the rendering of <details> in more detail. #10265

Specify the rendering of <details> in more detail. #10265

dbaron commented Apr 9, 2024 •

edited by pr-preview bot

Loading

dbaron commented Apr 9, 2024

domenic commented Apr 11, 2024

dbaron commented Apr 11, 2024

annevk left a comment

annevk Apr 15, 2024

dbaron Apr 18, 2024

annevk Apr 22, 2024

dbaron Jun 26, 2024

annevk Apr 15, 2024

dbaron Apr 18, 2024

annevk Apr 22, 2024

dbaron commented Apr 18, 2024

domenic left a comment

emilio commented Apr 22, 2024

emilio Apr 22, 2024

domenic Jun 20, 2024

dbaron Jun 20, 2024

domenic Jun 21, 2024

dbaron Jun 21, 2024

dbaron Jun 21, 2024

emilio Jun 21, 2024

dbaron commented Jun 3, 2024

bramus commented Jun 3, 2024

dbaron commented Jun 18, 2024

domenic left a comment

emilio left a comment

emilio Jun 21, 2024

dbaron Jun 25, 2024

emilio Jun 25, 2024

dbaron Jun 26, 2024

		<!-- TODO: link to CSS definition when spec is ready -->
		<p>This element is expected to match the '::details-content' pseudo-element.</p>

Specify the rendering of <details> in more detail. #10265

Specify the rendering of <details> in more detail. #10265

Conversation

dbaron commented Apr 9, 2024 • edited by pr-preview bot Loading

dbaron commented Apr 9, 2024

domenic commented Apr 11, 2024

dbaron commented Apr 11, 2024

annevk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dbaron commented Apr 18, 2024

domenic left a comment

Choose a reason for hiding this comment

emilio commented Apr 22, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dbaron commented Jun 3, 2024

bramus commented Jun 3, 2024

dbaron commented Jun 18, 2024

domenic left a comment

Choose a reason for hiding this comment

emilio left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dbaron commented Apr 9, 2024 •

edited by pr-preview bot

Loading