> argument
The ''::slotted()'' pseudo-element can be followed by a tree-abiding pseudo-element,
like ''::slotted()::before'',
representing the appropriate pseudo-element of the elements represented by the ''::slotted()'' pseudo-element.
The [=specificity=] of ''::slotted()'' is that of a pseudo-element,
plus the [=specificity=] of its argument.
For example, say you had a component with both children and a shadow tree,
like the following:
<x-foo>
<div id="one" slot="foo" class="foo">...</div>
<div id="two" slot="foo">...</div>
<div id="three" class="foo">
<div id="four" slot="foo">...</div>
</div>
<"shadow tree">
<div id="five">...</div>
<div id="six">...</div>
<slot name="foo"></slot>
</"shadow tree">
</x-foo>
For a stylesheet within the
shadow tree,
a selector like ''::slotted(*)''
selects ''#one'' and ''#two'' only,
as they're the elements
assigned to the sole <{slot}> element.
It will
not select ''#three''
(no
slot attribute)
nor ''#four''
(only direct
children of a
shadow host can be assigned to a
slot).
A selector like ''::slotted(.foo)'',
on the other hand,
will only select ''#one'',
as it matches ''.foo'',
but ''#two'' doesn't.
Note: Note that a selector like ''::slotted(*)''
is equivalent to ''*::slotted(*)'',
where the ''*'' selects many more elements than just the <{slot}> element.
However, since only the <{slot}> elements are
slots,
they're the only elements with a ''::slotted()'' pseudo-element as well.
Shadow Trees and the Cascade
See [[css-cascade-4#cascade-sort]].
Flattening the DOM into an Element Tree
While Selectors operates on the DOM tree as the host language presents it,
with separate trees that are unreachable via the standard parent/child relationship,
the rest of CSS needs a single unified tree structure to work with.
This is called the flattened element tree
(or flat tree),
and is constructed as follows:
1. Let pending nodes be a list of DOM nodes with associated parents,
initially containing just the document's root element with no associated parent.
2. Repeatedly execute the following substeps until pending nodes is empty:
1. Pop the first element from pending nodes,
and assign it to pending node.
2. Insert pending node into the flat tree
as a child of its associated parent.
(If it has no associated parent,
it's the document root--
just insert it into the flat tree as its root.)
3. Perform one of the following,
whichever is the first that matches:
- pending node is a shadow host
-
Append the child nodes of the shadow root of the shadow tree it hosts
to pending nodes,
with pending node as their associated parent.
- pending node is a slot
-
Find slottables for pending node,
and append them to pending nodes,
with pending node as their associated parent.
If no slottables were found for pending node,
instead append its children to pending nodes,
with pending node as their associated parent.
- Otherwise,
-
Append the child nodes of pending node’s light tree
to pending nodes,
with pending node as their associated parent.
Note: In other words, the flat tree is the top-level DOM tree,
but shadow hosts are filled with their shadow tree children
instead of their light tree children
(and this proceeds recursively if the shadow tree contains any shadow hosts),
and slots get filled with the nodes that are assigned to them
(and this proceeds recursively if the slots are themselves
assigned to a slot in a deeper shadow tree).
Issue: A non-obvious result of this
is that elements assigned to a slot inherit from that slot,
not their light-tree parent
or any deeper slots their slot gets assigned to.
This means that text nodes are styled by the shadow tree of their parent,
with nobody else capable of intervening in any way.
Do we want an additional pseudo-element for targeting those text nodes
so they can be styled at all slot-assignment levels,
like normal elements can be?
This implies it needs to work for text nodes in the light tree
before they're assigned downwards,
so this can't just be a ''::slotted()'' variant.
Luckily, this is a long-standing request!
Slots and Slotted Elements in a Shadow Tree
Slots must act as if they were assigned ''display: contents''
via a rule in the UA origin.
This must be possible to override via 'display',
so they do generate boxes if desired.
Note: A non-obvious result of assigning elements to slots
is that they inherit from the slot they're assigned to.
Their original light tree parent,
and any deeper slots that their slot gets assigned to,
don't affect inheritance.
Name-Defining Constructs and Inheritance
[=Shadow trees=] are meant to be an encapsulation boundary,
allowing independent authors to share code
without accidentally polluting each other's namespaces.
For example, element IDs,
which are generally meant to be unique within a document,
can be validly used multiple times
as long as each use is in a different [=shadow tree=].
Similarly, several [=at-rules=] in CSS,
such as ''@keyframes'' or ''@font-face'',
define a name that later at-rules or properties can refer to them by.
Like IDs, these names are globally exposed and unique within a document;
also like IDs,
this restriction is now loosened to being unique within a given [=shadow tree=].
However, property inheritance can carry values from one tree to another,
which complicates referencing the correct definition of a given name.
Done naively, this can produce surprising and confusing results for authors.
This section defines a set of concepts to use in defining and referencing "global" names
in a way that respects encapsulation
and doesn't give surprising results.
If an at-rule or property defines a name that other CSS constructs can refer to it by,
such as a ''@font-face'' '@font-face/font-family!!descriptor' name
or an ''@keyframes'' name,
it must be defined as a tree-scoped name.
[=Tree-scoped names=] are "global" within a particular [=node tree=];
unless otherwise specified,
they're associated with the [=root=] of the [=element=] hosting the stylesheet that the at-rule or property is defined in.
Properties or descriptors that reference a "global" name,
such as the 'font-family!!property'
or 'animation-name' properties,
must define their value as a tree-scoped reference.
[=Tree-scoped references=] implicitly capture
a [=node tree=] [=root=]
along with their specified value:
unless otherwise specified,
the [=root=] of the [=element=] hosting the stylesheet that the property or descriptor is defined in.
This [=root=] reference stays with the [=tree-scoped reference=]
as it is inherited.
Whenever a [=tree-scoped reference=] is dereferenced
to find the CSS construct it is referencing,
first search only the [=tree-scoped names=] associated with the same [=root=]
as the [=tree-scoped reference=] must be searched.
If no relevant [=tree-scoped name=] is found,
and the [=root=] is a [=shadow root=],
then repeat this search in the [=root=]'s [=host=]'s [=node tree=].
(In other words, [=tree-scoped names=] "inherit" into descendant shadow trees,
so long as they don't define the same name themselves.)
TODO: Fix all the at-rules that define global names,
and the properties that reference them,
to use these concepts.
* ''@font-face'', referenced by 'font-family!!property'
* ''@font-feature-values'', referenced by 'font-family!!property'
* ''@keyframes'', referenced by 'animation-name'
* ''@counter-style'', referenced by 'list-style-type'
* ''@color-profile'', referenced by the ''color()'' function
* ''@font-palette-values'', referenced by 'font-palette'
* others?
For example,
given the following document
(using the imaginary <::shadow> markup
to indicate an element's [=shadow tree=]):
<![CDATA[
<p class=outer>Here's some text in the outer document's "foo" font.
<style>
@font-face {
font-family: foo;
src: url(https://example.com/outer.woff);
}
body { font-family: foo; }
my-component::part(text) { font-family: foo; }
</style>
<my-component>
<::shadow>
<p class=inner-default>I'm inheriting the outer document's font-family.
<p class=inner-styled>And I'm explicitly styled to be in the component's "foo" font.
<p class=part-styled part=text>
I'm explicitly styled by the outer document,
and get the outer document's "foo" font.
<style>
@font-face {
font-family: foo;
src: url(https://example.com/inner.woff);
}
.inner-styled { font-family: foo; }
</style>
</::shadow>
</my-component>
]]>
The ''.outer'' element references the outer ''@font-face'', using the "outer.woff" file.
The ''.inner-default'' element inherits the ''font-family: foo'' value from the outer document,
using the same [=tree-scoped reference=] as ''.outer'',
and thus also uses the "outer.woff" font file.
The ''.inner-style'' element, on the other hand,
receives a ''font-family: foo'' from the stylesheet inside the shadow,
and thus its [=tree-scoped reference=] refers to the shadow's ''@font-family'',
and it uses the "inner.woff" file.
The ''.part-styled'' element also receives its style from the outer document,
tho by being directly set rather than by inheritance.
Thus, its [=tree-scoped reference=] also refer's to the outer document,
and it uses the "outer.woff" file.
Here is a more complex example,
showing three levels of trees,
and illustrating precisely how [=tree-scoped names=] and [=tree-scoped references=] inherit.
<![CDATA[
<style>
@font-face {
font-family: foo;
src: url(https://example.com/outer.woff);
}
body { font-family: foo; }
</style>
<child-component>
<::shadow>
<style>
@font-face {
font-family: foo;
src: url(https://example.com/inner.woff);
}
</style>
<grandchild-component>
<::shadow>
<p class=inner-default>
I'm inheriting the outer document's "foo" font.
</p>
<p class=inner-search>
And I can't find a local "foo" font,
so I'm searching further up the tree,
and find the shadow's "foo" font.
</p>
<style>
.inner-search { font-family: foo; }
</style>
</::shadow>
</grandchild-component>
</::shadow>
</child-component>
]]>
Here, just as in the previous example,
''.inner-default'' is inheriting the ''font-family: foo'' declared in the outer document,
and so it ends up referencing the outer document's ''@font-face'',
and is rendered with the "outer.woff" file.
On the other hand,
''.inner-search'' receives its style from a stylesheet in
<grandchild-component>'s shadow tree,
so it attempts to find a ''@font-face'' defining a ''foo'' font in that tree.
There is no such ''@font-face'',
so it starts walking up the shadow trees,
finding an appropriate ''@font-face'' in
<child-component>,
so it's rendered with the "inner.woff" file.
Serialized Tree-Scoped References
If a [=tree-scoped reference=] is serialized,
it serializes only its value;
the associated [=root=] is lost.
This implies that `el.style.foo = getComputedStyle(el).foo;`
is not necessarily a no-op,
like it typically was before [=shadow trees=] existed.
For example,
given the following document
(using the imaginary <::shadow> markup
to indicate an element's [=shadow tree=]):
<![CDATA[
<p class=outer>Here's some text in the outer document's "foo" font.
<style>
@font-face {
font-family: foo;
src: url(foo.woff);
}
body { font-family: foo; }
</style>
<my-component>
<::shadow>
<p class=inner-default>I'm inheriting the outer document's font-family.
<p class=inner-styled>And I'm explicitly styled to be in the component's "foo" font.
<style>
@font-face {
font-family: foo;
src: url(https://example.com/foo.woff);
}
.inner-styled { font-family: foo; }
</style>
<script>
const innerDefault = document.querySelector('.inner-default');
const innerStyled = document.querySelector('.inner-styled');
const defaultFont = getComputedStyle(innerDefault).fontFamily;
const styledFont = getComputedStyle(innerStyled).fontFamily;
console.log(defaultFont == styledFont); // true!
</script>
</::shadow>
</my-component>
]]>
The
.outer element is styled with the outer document's "foo" ''@font-face''.
The
.inner-default element inherits 'font-family' from the outer document,
meaning it inherits a [=tree-scoped reference=]
referencing that outer document,
and so it's in the same font as
.outer.
Meanwhile,
.inner-styled is explicitly styled from inside the shadow root,
so it receives a fresh [=tree-scoped reference=]
referencing its shadow tree,
and it is instead styled the shadow's own "foo" ''@font-face''.
Despite that, the script running inside the component
sees the two elements as having the same value for 'font-family',
because the [=root=]-reference part of a [=tree-scoped reference=]
is not preserved by serialization.
If it were to set
innerDefault.style.fontFamily = defaultFont;
(thus setting the 'font-family' property of the element's attribute stylesheet,
which lives in the shadow tree),
the
.inner-default element would suddenly switch
to the same font as
.inner-styled!
Changes
The following significant changes were made since the
3 April 2014 Working Draft.
* Defined that tree-scoped names inherit into descendant shadow trees
* Renamed ::content to ''::slotted''.
* Define the flattened tree.
* Generally reorg and rebase the Shadow DOM section on top of current DOM.
* Punt @scope and related things,
and ::region and related things,
to the next level of the draft.
* Define the specificity of '':host'', '':host()'', '':host-context()'', and ''::slotted()''
* Remove the >>> (previously called /deep/) combinator.
* Define that tree-abiding pseudos are allowed after ''::slotted()''.
* Allow <> in all the pseudos.
* Define a way to create a stylesheet of default element styles for a given element.
* Make featureless elements match nothing.
* Define in the context of a shadow tree.
Privacy Considerations {#privacy}
===============================================
This specification introduces Shadow DOM and some shadow-piercing capabilities,
but this does not introduce any privacy issues--
shadow DOM, as currently specified, is intentionally not a privacy boundary
(and the parts of the UA that use shadow DOM and do have a privacy boundary
implicitly rely on protections not yet specified,
which protect them from the things defined in this specification).
Security Considerations {#security}
===============================================
This specification introduces Shadow DOM and some shadow-piercing capabilities,
but this does not introduce any security issues--
shadow DOM, as currently specified, is intentionally not a security boundary
(and the parts of the UA that use shadow DOM and do have a security boundary
implicitly rely on protections not yet specified,
which protect them from the things defined in this specification).