1. Introduction

This spec is intentionally a rough sketch at the moment. +It should contain all the details necessary to evaluate the proposal.

Shadow DOM allows authors to separate their page into "components", +subtrees of markup whose details are only relevant to the component itself, +not the outside page. +This reduces the chance of a style meant for one part of the page +accidentally over-applying and making a different part of the page look wrong. +However, this styling barrier also makes it harder for a page to interact with its components +when it actually wants to do so.

This specification defines the ::part() and ::theme() pseudo-elements, +which allow an author to style specific, purposely exposed elements in a shadow tree from the outside page’s context. +In combination with custom properties, +which let the outside page pass particular values +(such as theme colors) +into the component for it to do with as it will, +these pseudo-elements allow components and the outside page +to interact in safe, powerful ways, +maintaining encapsulation +without surrending all control.

1.1. Motivation

For obvious reasons, +it’s valuable to let the outside page style the internals of a shadow tree, +at least in some limited ways. +(The ubiquity of UA-specific pseudo-elements for the various input elements shows this.)

The previous proposed method for doing so, +the >>> combinator, +turned out to be too powerful for its own good; +it exposed too much of a component’s internal structure to scrutiny, +defeating some of the encapsulation benefits that using Shadow DOM brings. +For this, +and other performance-related reasons, +the >>> combinator was eventually removed from the live profile.

This left us with using custom properties as the only way to style into a shadow tree: +the component would advertise that it uses certain custom properties to style its internals, +and the outer page could then set those properties as it wished on the shadow host, +letting inheritance push the values down to where they were needed. +This works very well for many simple theming use-cases.

However, there are some cases where this falls down. +If a component wishes to allow arbitrary styling of something in its shadow tree, +the only way to do so is to define hundreds of custom properties (one per CSS property they wish to allow control of), +which is obviously ridiculous +for both usability and performance reasons. +The situation is compounded if authors wish to style the component differently +based on pseudo-classes like :hover; +the component needs to duplicate the custom properties used +for each pseudo-class +(and each combination, +like :hover:focus, +resulting in a combinatorial explosion). +This makes the usability and performance problems even worse.

We introduce ::part() to handle this case much more elegantly and performantly. +Rather than bundling everything into custom property names, +the functionality lives in selectors and style rule syntax, +like it’s meant to. +This is far more usable for both component authors +and component users, +should have much better performance, +and allows for better encapsulation/API surface.

Another interesting facet of using custom properties, +however, +is that inheritance doesn’t stop at the first shadow tree. +Unless explicitly blocked, +a custom property inherits down thru nested trees, +allowing authors to style deeply nested components +as easily as they style directly-visible ones. +The same considerations apply to this case, +so we introduce ::theme() to handle this.

It’s important to note that ::part() and ::theme() offer absolutely zero new theoretical power. +They are not a rehash of the >>> combinator, +they’re simply a more convenient and consistent syntax +for something authors can already do with custom properties. +By separating out the explicitly "published" parts of an element +(the shadow part map from the sub-parts that it merely happens to contain +(the computed shadow theme map, +it also helps with encapsulation, +as authors can use ::part() without fear of accidental over-styling.

2. Exposing a Shadow Element:

Each element has a part name list which is an ordered sets of tokens.

Each element has a part name map which is an ordered map, +with keys that are tokens +and values that are ordered sets of tokens.

Each shadow root has a shadow part element map with keys that are strings and values that are ordered sets of elements.

The shadow part element map is described +only as part of the algorithm for calculating style in this spec. +It is not exposed via the DOM, +as calculating it may be expensive +and doing so could allow access to elements inside closed shadow roots.

Shadow part element maps are affected by the addition and removal of elements +and changes to the part name lists and part name maps of elements in the DOM.

To calculate the shadow part element map of a shadow root

+
1. + For each element within this "outer" shadow root +
   +
   1. For each name in the element’s part name list, + add this element to outer-shadow-root-part-map[name] +
   2. + If the element is a shadow host: +
      +
      1. Calculate the shadow part element map of its shadow root ("inner" shadow root). +
      2. For each key ("outer name") in the outershadow root part name map + and for each token ("inner name") in that key’s ordered set of tokens + look up inner-shadow-root-part-map[inner name] to get a (possibly empty) set of elements + and add these elements to outer-shadow-poot-part-map[outer name]. +
      +
   +

Include wild-card forwarding in algortihm.

There is no need for the shadow part element map values to be ordered, can we drop that?

2.1. Naming a Shadow Element: the part attribute

Any element in a shadow tree can have a part attribute. +This is used to expose the element outside of the shadow tree.

The part attribute is parsed as a space-separated list of tokens representing the part names of this element.

Note: It’s okay to give a part multiple names. +The "part name" should be considered similar to a class, +not an id or tagname.

<style>
+  c-e::part(textspan) { color: red; }
+</style>
+
+<template id="c-e-template">
+  <span part="textspan">This text will be red</span>
+</template>
+<c-e></c-e>
+<script>
+  // Add template as custom elment c-e
+  ...
+</script>
+

2.2. Forwarding a Shadow Element: the partmap attribute

The partmap attribute is parsed as a comma-separated list of part mappings. +Each part mapping is one of:

+

ident1 => ident2 +

+

If el is a shadow host, +and it’s shadow root’s shadow part map partMap contains ident1, +then this adds «[ ident2 → partMap[ident1] ]» to the shadow part map of the shadow root containing el.

+

ident +

+

Is equivalent to ident => ident.

+

* => prefix* +

+

If el is a shadow host, +then for each ident → subEl in el’s shadow root’s shadow part map, +«[ prefix + ident → subEl ]» is added to the shadow part map of the shadow root containing el.

+

anything else +

+

Ignored for error-recovery / future compat.

+

When doing prefixed-wildcard forwarding, should probably automatically exclude sub-parts that are manually forwarded. With that, would be good to have a syntax to block forwarding of a sub-part (currently would require `foo => nonsense-name`).

Note: It’s okay to map a sub-part to several names.

<style>
+  c-e::part(textspan) { color: red; }
+</style>
+
+<template id="c-e-outer-template">
+  <span part="textspan">
+    This text will be red because the document style matches it directly.
+  </span>
+  <c-e-inner partmap="innerspan => textspan"></c-e-inner>
+</template>
+
+<template id="c-e-inner-template">
+  <span part="innerspan">
+    This text will be red because the containing shadow host exposes <b>innerspan</b> to the document as "textspan" and the document style matches it.
+  </span>
+</template>
+
+<c-e></c-e>
+<script>
+  // Add template as custom elments c-e-inner c-e-outer
+    ...
+</script>
+

2.3. Exposing More Widely: the theme attribute

In addition to the shadow part map, +every shadow root has a partial shadow theme map and a computed shadow theme map both of which are ordered maps (with the same key/value shape as the shadow part map), +and the elements in the shadow tree have a corresponding theme attribute.

The theme attribute is parsed and interpreted identically to the part attribute, +except that it adds its entries to the shadow root’s partial shadow theme map instead.

If the shadow root’s mode is "closed", +the computed shadow theme map is identical to the partial shadow theme map. +Otherwise, +it’s the union of the partial shadow theme map with the computed shadow theme maps of every shadow host’s shadow root in its shadow tree.

3. Selecting a Shadow Element: the ::part() and ::theme() pseudo-elements

The ::part() and ::theme() pseudo-elements +(collectively, the shadow-part pseudo-elements) +allow you to select elements that have been exposed via a part attribute. +The syntaxes of them are:

::part() = ::part( <ident> )
+::theme() = ::theme( <ident> )
+

The ::part() pseudo-element only matches anything +when the originating element is a shadow host. +If the originating element’s shadow root’s shadow part element map contains the specified <ident>, ::part() matches the element or elements keyed to that <ident>. +Otherwise, it matches nothing.

The ::theme() pseudo-element is similar, +except it can match regardless of whether the originating element is a shadow host or not. +It matches the elements keyed to the specified <ident> in the computed shadow theme map of the shadow trees of the originating element or any descendants.

The shadow-part pseudo-elements can take additional pseudo-classes after them, +such as x-button::part(label):hover, +but never match the structural pseudo-classes or any other pseudo-classes that match based on tree information +rather than local element information.

The shadow-part pseudo-elements also can take additional pseudo-elements after them, +such as x-button::part(label)::before, +but never match additional shadow-part pseudo-elements.

4. Extensions to the Element Interface

dictionary PartMap {
+  required DOMTokenList mappedParts = null;
+};
+
+partial interface Element {
+  [SameObject] readonly attribute DOMTokenList partList;
+  [SameObject] readonly attribute PartMap partMap;
+};
+

The partList attribute must return a DOMTokenList object whose associated element is the context object and whose associated attribute’s local name is part. +The token set of this particular DOMTokenList object are also known as the element’s part names.

The partMap attribute must return a dictionary object whose associated element is the context object and whose associated attribute’s local name is partmap.

Document the relationship between the values in partMap and the partmap attribute.