8000 [css-scoping] mostly done importing new shadow dom stuff · w3c/csswg-drafts@387e1d3 · GitHub
Skip to content

Commit 387e1d3

Browse files
tabatkinstabatkins
committed
[css-scoping] mostly done importing new shadow dom stuff
1 parent e17f6ef commit 387e1d3

1 file changed

Lines changed: 123 additions & 98 deletions

File tree

‎css-scoping/Overview.bs‎

Lines changed: 123 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -238,57 +238,46 @@ Selecting Outside the Scope: '':scope-context()'' pseudo-class</h4>
238238
<h2 id='shadow-dom'>
239239
Shadow Encapsulation</h2>
240240

241-
The Shadow DOM spec augments the DOM with several new concepts,
241+
<h3 id='shadow-gloss'>
8000 242+
Informative Explanation of Shadow DOM</h3>
243+
244+
<em>The following is a non-normative explanation
245+
of several concepts normatively defined in the DOM Standard [[!DOM]],
246+
to aid in understanding what this spec defines
247+
without having to fully grok the DOM Standard.</em>
248+
249+
In addition to the qualities of an element tree defined in [[SELECTORS4#data-model]],
250+
the DOM Standard adds several new concepts related to <a>shadow trees</a>,
242251
several of which are relevant to CSS.
243252

244-
A <a>shadow tree</a> is a document fragment
245-
that can be attached to any element in the DOM.
246-
The root of the <a>shadow tree</a> is a <a>shadow root</a>,
247-
a non-element node which is associated with a <a>shadow host</a>.
248-
An element can have any number of <a>shadow trees</a>,
249-
which are ordered by creation time.
250-
251-
An element with a <a>shadow tree</a> is a <dfn export>shadow host</dfn>.
252-
It is the <a>host</a> for its <a>shadow trees</a>.
253-
254-
The descendants of a <a>shadow host</a>
255-
(its <a>light tree</a>)
256-
must not generate boxes in the formatting tree.
257-
Instead, the contents of the <a>shadow tree</a> generate boxes
258-
as if they were the contents of the <a>shadow host</a> instead.
259-
260-
In several instances in shadow DOM,
261-
elements don't have element parents
262-
(instead, they may have a <a>shadow root</a> as parent,
263-
or something else).
264-
An element without a parent,
265-
or whose parent is not an element,
266-
is called a <dfn export>top-level element</dfn>.
267-
268-
While a <a>shadow host's</a> <a>light tree</a> does not generate boxes normally,
269-
its <a>light tree</a> direct <a>children</a> can be explicitly pulled into a <a>shadow tree</a>
270-
and forced to render normally.
271-
This is done by marking the child as <a>slotable</a>
272-
and then,
273-
in the <a>shadow tree</a>,
274-
creating a <a>slot</a> set to receive the <a>slotable</a>,
275-
making the element <dfn export lt="slot-assign|assigned to a slot|assigned to the slot" local-lt="assign">assigned to the slot</dfn>.
276-
(Anonymous text nodes that are direct children are always <a>slotable</a>.)
277-
278-
Note: The DOM specification [[!DOM]] defines how to make elements <a>slotable</a>,
279-
what elements are <a>slots</a>,
280-
and how the two are matched together.
281-
282-
283-
<h3 id='selectors-data-model'>
284-
Shadow DOM Selection Model</h3>
285-
286-
Elements in the DOM
287-
have zero or more <a>shadow trees</a>.
288-
289-
Note: The "descendants" of an element
290-
are based on the <a>light tree</a> children of the element,
291-
which does not include the <a>shadow trees</a> of the element.
253+
An element can host a <a>shadow tree</a>,
254+
which is a special kind of document fragment
255+
with a <a>shadow root</a>
256+
(a non-element node)
257+
at its root.
258+
Children of the <a>shadow root</a> are ordinary elements and other nodes.
259+
The element hosting the <a>shadow tree</a> is its <a>host</a>,
260+
or <dfn export>shadow host</dfn>.
261+
262+
The elements in a <a>shadow tree</a> are not <a>descendants</a> of the <a>shadow host</a> in general
263+
(including for the purposes of Selectors like the <a>descendant combinator</a>).
264+
However, the <a>shadow tree</a>,
265+
when it exists,
266+
is used in the construction of the <a>flattened element tree</a>,
267+
which CSS uses for all purposes <em>after</em> Selectors
268+
(including inheritance and box construction).
269+
270+
Loosely, the <a>shadow tree</a> is treated as the <a>shadow host's</a> contents
271+
instead of its normal <a>light tree</a> contents.
272+
However, some of its <a>light tree</a> children
273+
can be "pulled into" the <a>shadow tree</a>
274+
by assigning them to <a>slots</a>.
275+
276+
<h3 id='selectors'>
277+
Shadow DOM and Selectors</h3>
278+
279+
<h4 id='selectors-data-model'>
280+
Matching Selectors Against Shadow Trees</h4>
292281

293282
When a selector is matched against a <a>shadow tree</a>,
294283
the <a>selector match list</a>
@@ -297,10 +286,14 @@ Shadow DOM Selection Model</h3>
297286
and their descendants,
298287
ordered by a pre-order traversal.
299288

289+
Note: Remember that the <a>descendants</a> of an element
290+
are based on the <a>light tree</a> <a>children</a> of the element,
291+
which does not include the <a>shadow trees</a> of the element.
292+
300293
When a selector is <a lt="match a selector against a tree">matched against a tree</a>,
301294
its <dfn export>tree context</dfn> is the <a>root</a> of the <var>root elements</var> passed to the algorithm.
302295
If the <a>tree context</a> is a <a>shadow root</a>,
303-
that selector is being matched <dfn>in the context of a shadow tree</dfn>.
296+
that selector is being matched <dfn export lt="in the context of a shadow tree|in the context of the shadow tree">in the context of a shadow tree</dfn>.
304297

305298
<div class="example">
306299
For example,
@@ -313,32 +306,31 @@ Shadow DOM Selection Model</h3>
313306
of the selector that was matched to apply them.
314307

315308
<h4 id='host-element-in-tree'>
316-
Shadow Hosts in a Shadow Tree</h4>
309+
Selecting Shadow Hosts from within a Shadow Tree</h4>
317310

318-
A <a>shadow host</a> is outside of the <a>shadow trees</a> it hosts,
311+
A <a>shadow host</a> is outside of the <a>shadow tree</a> it hosts,
312+
and so would ordinarily be untargettable by any selectors evaluated <a>in the context of the shadow tree</a>
313+
(as selectors are limited to a single tree),
319314
but it is sometimes useful to be able to style it from inside the <a>shadow tree< 8097 ;/a> context.
320315

321316
For the purpose of Selectors,
322-
a <a>shadow host</a> also appears in each of its <a>shadow trees</a>,
317+
a <a>shadow host</a> also appears in its <a>shadow tree</a>,
323318
with the contents of the <a>shadow tree</a> treated as its children.
324-
If an element has multiple <a>shadow trees</a>,
325-
it appears in each <a>shadow tree's</a> context independently;
326-
each <a>shadow tree</a> sees <em>itself</em> as the contents of the <a>shadow host</a>,
327-
not the other <a>shadow trees</a>.
319+
(In other words, the <a>shadow host</a> is treated as replacing the <a>shadow root</a> node.)
328320

329321
When considered within its own <a>shadow trees</a>,
330322
the <a>shadow host</a> is <a>featureless</a>.
331323
Only the '':host'', '':host()'', and '':host-context()'' pseudo-classes are allowed to match it.
332324

333-
<details class='why'>
325+
<details class='note'>
334326
<summary>Why is the shadow host so weird?</summary>
335327

336328
The <a>shadow host</a> lives outside the <a>shadow tree</a>,
337329
and its markup is in control of the page author,
338330
not the component author.
339331

340332
It would not be very good if a component used a particular class name
341-
internally in a <a>shadow tree</a>,
333+
internally in a <a>shadow tree</a> stylesheet,
342334
and the page author using the component accidentally <em>also</em>
343335
used the the same class name and put it on the <a>shadow host</a>.
344336
Such a situation would result in accidental styling
@@ -347,46 +339,15 @@ Shadow Hosts in a Shadow Tree</h4>
347339

348340
However, there are still some reasonable use-cases for letting a stylesheet in a <a>shadow tree</a>
349341
style its <a>shadow host</a>.
342+
(For example,
343+
the component might want to be laid out as a flexbox,
344+
requiring the <a>shadow host</a> to be set to ''display: flex''.)
350345
So, to allow this situation but prevent accidental styling,
351346
the <a>shadow host</a> appears but is completely featureless
352-
and unselectable except through '':host''.
347+
and unselectable except through '':host'' and its related functional forms,
348+
which make it very explicit when you're trying to match against markup provided by the page author.
353349
</details>
354350

355-
<h4 id='slots-in-shadow-tree'>
356-
Slots and Slotted Elements in a Shadow Tree</h4>
357-
358-
<a>Slots</a> must act as if they were assigned ''display: contents'' in the <a>UA origin</a>.
359-
This must be possible to override via 'display',
360-
so they <em>do</em> generate boxes if desired.
361-
362-
If a <a>slot</a> is not <a>assigned</a> any of its <a>shadow host's</a> children,
363-
that <a>slot's</a> own <a>children</a>
364-
are <a>assigned</a> to it.
365-
Otherwise, a <a>slot's</a> DOM <a>children</a>
366-
must not generate any boxes,
367-
as if they were ''display:none''.
368-
369-
<a>Slots</a> can, themselves, be <a>assigned</a> to a <a>slot</a> in a deeper shadow tree.
370-
If this occurs,
371-
the elements <a>assigned</a> to the first slot
372-
are also treated as being <a>assigned</a> to the deeper <a>slot</a>.
373-
The deepest <a>slot</a> that an element is <a>assigned</a> to is its <dfn export>final assigned slot</dfn>.
374-
375-
Elements <a>assigned</a> to a <a>slot</a>
376-
must generate boxes as if they were children of their <a>final assigned slot</a>
377-
(rather than children of their actual parent in a <a>shadow host's</a> <a>light tree</a>).
378-
379-
380-
<h3 id='selectors'>
381-
Shadow DOM Selectors</h3>
382-
383-
Shadow DOM defines a few new selectors
384-
to help select elements in useful way related to Shadow DOM.
385-
386-
Issue: This section is still under discussion.
387-
Feedback and advice on intuitive syntax for the following functionality
388-
would be appreciated.
389-
390351
<!--
391352
██ ██ ██ ███████ ██████ ████████
392353
████ ██ ██ ██ ██ ██ ██ ██
@@ -507,7 +468,7 @@ Selecting Slot-Assigned Content: the ''::slotted()'' pseudo-element</h4>
507468

508469
The ''::slotted()'' pseudo-element represents the elements that are:
509470

510-
* <a>assigned</a> to its <a>originating element</a>
471+
* <a lt="find distributed slotables">distributed</a> to the <a>slot</a> that is ''::slotted''’s originating element
511472
* <a lt="match a selector against an element">matched</a> by its <<compound-selector>> argument
512473

513474
<div class="example">
@@ -564,8 +525,6 @@ Selecting Slot-Assigned Content: the ''::slotted()'' pseudo-element</h4>
564525
<h4 id='deep-combinator'>
565526
Selecting Through Shadows: the ''>>>'' combinator</h4>
566527

567-
Issue: It's currently disputed whether this combinator should exist.
568-
569528
When a <dfn selector id="selectordef-shadow-piercing-descendant-combinator">>>></dfn> combinator
570529
(or <dfn export>shadow-piercing descendant combinator</dfn>)
571530
is encountered in a selector,
@@ -598,6 +557,72 @@ Selecting Through Shadows: the ''>>>'' combinator</h4>
598557
''#top'', ''#not-top'', <em>and</em> ''#nested''.
599558
</div>
600559

560+
The <a>shadow-piercing descendant combinator</a> is part of the <a>static profile</a> of Selectors,
561+
not the <a>dynamic profile</a>.
562+
This means that it is usable in,
563+
for example, the {{querySelector()}} method,
564+
but is invalid when used in stylesheets.
565+
566+
<!-- Big Text: Flat Tree -->
567+
568+
<h3 id='flattening' algorithm>
569+
Flattening the DOM into an Element Tree</h3>
570+
571+
While Selectors operates on the DOM tree as the host language presents it,
572+
with separate trees that are unreachable via the standard parent/<a>child</a> relationship,
573+
the rest of CSS needs a single unified tree structure to work with.
574+
This is called the <dfn export lt="flat tree|flattened element tree">flattened element tree</dfn>
575+
(or <a>flat tree</a>),
576+
and is constructed as follows:
577+
578+
1. Let <var>pending nodes</var> be a list of DOM nodes with associated parents,
579+
initially containing just the document's <a>root</a> element with no associated parent.
580+
2. Repeatedly execute the following substeps until <var>pending nodes</var> is empty:
581+
1. Pop the first element from <var>pending nodes</var>,
582+
and assign it to <var>pending node</var>.
583+
2. Insert <var>pending node</var> into the <a>flat tree</a>
584+
as a child of its associated parent.
585+
(If it has no associated parent,
586+
it's the document root--
587+
just insert it into the <a>flat tree</a> as its root.)
588+
3. Perform one of the following,
589+
whichever is the first that matches:
590+
591+
<dl class=switch>
592+
<dt><var>pending node</var> is a <a>shadow host</a>
593+
<dd>
594+
Append the child nodes of the <a>shadow root</a> of the <a>shadow tree</a> it hosts
595+
to <var>pending nodes</var>,
596+
with <var>pending node</var> as their associated parent.
597+
<dt><var>pending node</var> is a <a>slot</a>
598+
<dd>
599+
Find the <a>slotables</a> for whom <var>pending node</var> is their <a>final distributed slot</a>,
600+
and append them to <var>pending nodes</var>,
601+
with <var>pending node</var> as their associated parent.
602+
<dt>Otherwise,
603+
<dd>
604+
Append the child nodes of <var>pending node</var>’s <a>light tree</a>
605+
to <var>pending nodes</var>,
606+
with <var>pending node</var> as their associated parent.
607+
</dl>
608+
609+
Note: In other words, the <a>flat tree</a> is the top-level DOM tree,
610+
but <a>shadow hosts</a> are filled with their <a>shadow tree</a> children
611+
instead of their <a>light tree</a> children
612+
(and this proceeds recursively if the <a>shadow tree</a> contains any <a>shadow hosts</a>),
613+
and <a>slots</a> get filled with the nodes that are distributed to them.
614+
615+
<h4 id='slots-in-shadow-tree'>
616+
Slots and Slotted Elements in a Shadow Tree</h4>
617+
618+
<a>Slots</a> must act as if they were assigned ''display: contents'' in the <a>UA origin</a>.
619+
This must be possible to override via 'display',
620+
so they <em>do</em> generate boxes if desired.
621+
622+
Issue: Maybe gloss slots.
623+
DOM needs to define the <a>final distributed slot</a> concept;
624+
I can't easily derive it from the existing definitions.
625+
601626
<!--
602627
██████ ███ ██████ ██████ ███ ████████ ████████
603628
██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██ ██

0 commit comments

Comments
 (0)