CSS Shadow Parts

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.