Skip to content

Commit

Permalink
Specify the rendering of <details> in more detail
Browse files Browse the repository at this point in the history 
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](https://bugs.webkit.org/show_bug.cgi?id=157323).)

* It removes the restriction that <details> is a block and cannot be changed.  This is prototyped in Chromium and Gecko.  This fixes #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.
  • Loading branch information
@dbaron
dbaron authored Jun 26, 2024
1 parent ff064e7 commit e0e3b26
Showing 1 changed file with 61 additions and 23 deletions.
84 changes: 61 additions & 23 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4135,9 +4135,10 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li><dfn data-x-href="https://drafts.csswg.org/css-color-adjust/#pages-supported-color-schemes">page's supported color-schemes</dfn></li>
</ul>

<p>The following term is defined in <cite>CSS Pseudo-Elements</cite>: <ref>CSSPSEUDO</ref></p>
<p>The following terms are defined in <cite>CSS Pseudo-Elements</cite>: <ref>CSSPSEUDO</ref></p>

<ul class="brief">
<li><dfn data-x-href="https://drafts.csswg.org/css-pseudo/#details-content-pseudo">'::details-content'</dfn></li>
<li><dfn data-x-href="https://drafts.csswg.org/css-pseudo/#file-selector-button-pseudo">'::file-selector-button'</dfn></li>
</ul>

Expand Down Expand Up @@ -135009,6 +135010,9 @@ input[type=image i][align=bottom i], object[align=bottom i] {

<pre><code class="css">@namespace "http://www.w3.org/1999/xhtml";

details, summary {
display: block;
}
details > summary:first-of-type {
display: list-item;
counter-increment: list-item 0;
Expand All @@ -135018,28 +135022,62 @@ details[open] > summary:first-of-type {
list-style-type: disclosure-open;
}</code></pre>

<p>The <code>details</code> element is expected to render as a <span>block box</span>. The element
is also expected to have an internal <span>shadow tree</span> with two <span
data-x="concept-slot">slots</span>. The first <span data-x="concept-slot">slot</span> is expected
to take the <code>details</code> element's first <code>summary</code> element child, if any. The
second <span data-x="concept-slot">slot</span> is expected to take the <code>details</code>
element's remaining descendants, if any.</p>

<p>The <code>details</code> element's first <code>summary</code> element child, if any, is
expected to allow the user to request the details be shown or hidden.</p>

<p>The <code>details</code> element's second <span data-x="concept-slot">slot</span> 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 <code>details</code> element does not have an
<code data-x="attr-details-open">open</code> attribute. When it does have the <code
data-x="attr-details-open">open</code> attribute, the <code data-x="attr-style">style</code>
attribute is expected to be removed from the second <span data-x="concept-slot">slot</span>.</p>

<p class="note">Because the slots are hidden inside a shadow tree, this <code
data-x="attr-style">style</code> attribute is not directly visible to author code. Its impacts,
however, are visible. Notably, the choice of <code data-x="">content-visibility: hidden</code>
instead of, e.g., <code data-x="">display: none</code>, impacts the results of various APIs that
query layout information.</p>
<p>The <code>details</code> element is expected to have an internal <span>shadow tree</span> with
three child elements:</p>

<ol>
<li>
<p>The first 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>

<p>The <code>summary</code> element that this slot <span>represents</span> is expected to allow
the user to request the details be shown or hidden.</p>
</li>

<li>
<p>The second child element is a <code>slot</code> that is expected to take the
<code>details</code> element's remaining descendants, if any. This element has no contents.</p>

<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
<code>details</code> element does not have an <code data-x="attr-details-open">open</code>
attribute. When it does have the <code data-x="attr-details-open">open</code> attribute, the
<code data-x="attr-style">style</code> attribute is expected to be set to
"<code data-x="">display: block;</code>".</p>

<p class="note">Because the slots are hidden inside a shadow tree, this <code
data-x="attr-style">style</code> attribute is not directly visible to author code. Its impacts,
however, are visible. Notably, the choice of <code data-x="">content-visibility: hidden</code>
instead of, e.g., <code data-x="">display: none</code>, impacts the results of various APIs that
query layout information.</p>
</li>

<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 {
display: list-item;
counter-increment: list-item 0;
list-style: disclosure-closed inside;
}
:host([open]) summary {
list-style-type: disclosure-open;
}</code></pre>
<p class="note">The position of this child element relative to the other two is not observable.
This means that implementations might have it in a different order relative to its siblings.
Implementations might even associate the style with the shadow tree using a mechanism that is
not an element.</p>
</li>

</ol>

<p class="note">The structure of this shadow tree is observable through the ways that the children
of the <code>details</code> element and the '::details-content' pseudo-element respond to CSS
styles.</p>

<!-- https://mail.gnome.org/archives/usability/2006-June/msg00015.html -->

Expand Down

0 comments on commit e0e3b26

Please sign in to comment.