[css-shadow-parts-1] Can class name selectors apply to a part?

[JanMiksovsky]

We're experimenting with the shadow part support in Chrome (behind the flag), and have a number of situations where we'd like to conditionally style parts based on the state of the relevant part.

E.g., we have a Tabs component, and would like to expose the tab buttons as parts for styling. Significantly, the selected state of the tab button is relevant to styling, i.e., a selected tab button should look different than an unselected tab button.

The selected state of the tab button is not reflected in any existing pseudo-class. (While it'd be theoretically possible to reimplement the tab buttons as check boxes to expose the :checked pseudo-class, that's an extremely awkward approach just to get some styling.)

Short of having some way for components to expose custom pseudo-classes, we were wondering if it'd be possible to access classes on a part: e.g.,

my-tabs-component::part(tab-button) {
  color: black;
}

my-tabs-component::part(tab-button).selected {
  color: red;
}

Here the component author communicates part state to the outside world by applying CSS classes to the parts.

It's not explicitly indicated in https://drafts.csswg.org/css-shadow-parts/#part, but our experiments in Chrome at least suggest that the above is not supported. That places hard limits on how customizable we can make our components, even when ::part is widely supported.

It doesn't seem like supporting class selectors on a part leaks much critical information or would produce brittle components. If the component author needs to refactor their component's shadow tree — e.g., to replace one type of shadow element with a different type of element — it'd be safe for them to support the same class names on the new element.

[tabatkins]

No, this isn't possible, by design.

The point of ::part is to hide the internal details of the component, and expose only exactly the parts the component author explicitly wants to. Random classes are an internal detail; there's no telling what use the component author has for them, or whether they're appropriate for outside code to use.

One can give a single element multiple part names, and differentiate state based on that. I also thought that you could do, say, ::part(one two) to select only elements with both part names, but it turns out you can't; that's probably something we want to add, so you can more easily add a "selected" part name in your example, and then use ::part(tab-button selected).

@fergald , what do you think?

[JanMiksovsky]

@tabatkins Thanks for your thoughts! We care less about the precise mechanism and more about the scenario.

My initial thought is that your multiple-parts solution would probably be sufficient to support styling our tabs component and a number of similar components.

I do wonder if we'll hit cases where part state is more complex than a binary value, or multiple state values are in place. Another approach would give the author a way to expose only those part aspects that should be considered available for styling purposes. Using attributes as an example, something like

  <tab-button part="tab-button" part-attributes="selected" selected>Tab 1</tab-button>

might explicitly open up the component-specific selected attribute for styling:

my-tabs-component::part(tab-button)[selected] { ... }

We'll continue exploring the application of shadow parts to our library and look for cases were the current spec appears to be insufficient.

[fergald]

@tabatkins Implementaiton-wise, supporting multiple part names ANDed together seems easy. Adding a separate part-attributes would be considerably more complicated. Does attributes add any extra capabilities that are impossible with ::part(foo bar) or does it just add some namespacing?

[JanMiksovsky]

@fergald I'd suggested attributes so that someone could target specific values for non-binary attributes via attribute selectors: e.g., ::part(foo)[attr="value"].

I can certainly understand why multiple part names would be simpler. I'll do a preliminary review of our components looking for cases where that might not be sufficient.

[fergald]

I think there would be ergonomic advantages to [attr="value"] if you were able to set attributes indiviually as you can on a HTML element but if you're setting them inside part-attribute="attr=value" then there's very little win on top of just doing part="attr=value" which gives you a part named attr=value.

We also need to think about forwarding from deeper shadow-trees. Would we need a way to forward and rename attributes? If they're just part names we already have that ability (although we would want wildcard forwarding to be able to forward attr=value, see #3422).

[JanMiksovsky]

I've done an initial review of our Elix component library to look for situations where someone might want to style a part based on component state or part state. These components, roughly 60 in number, are intentionally generic in appearance so that they can eventually be styled to match an app's visual aesthetic or branding, so they seem like a reasonable corpus of use cases for shadow parts.

Initial findings

• 26 components have parts with a binary part state, like the selected example in the TabStrip example mentioned above.
• 21 components have parts with state reflected by a string that can take one of a limited set of values; i.e., an enum. Example: the MenuButton component has a horizontalAlign property that governs the alignment of the popup menu with respect to the button that invokes the menu. This horizontalAlign property takes one of 5 enumerated string values: "end", "left", "right", "start", or "stretch". If a MenuButton is exposed as a part, the designer may want to conditionally apply styling to that part based on that menu's horizontal alignment.
• 6 components have 2 or more parts that each expose part state, in some cases the same kind of state but with different visual semantics. E.g., a stock Carousel component has two subcomponents: 1) a sliding panel showing images or other content, and 2) a row of dots indicating which item is shown. Each subcomponent has elements it will want to expose as parts, and the outer Carousel will want to forward those parts to the outside world to make them available for styling. Significantly, both subcomponents support a selected state, but the visual semantics of selection differ: for the panel showing images/etc., the selected state governs visibility; for the dots, the selected state governs brightness or some other means of visually indicating selection.

So out of our 60 components, it looks like we'll hit this issue in a substantial portion of them.

I think allowing multiple part names will cover the scenarios I can envision so far. That said, for the 21 cases described above where state is essentially an enum, it'll get cumbersome to define part names for each enum value. In the horizontalAlign property, there are 5 possible string values, so we'll need to generate one of 5 part names to tack onto the part: horizontal-align-end, horizontal-align-left, horizontal-align-right, etc.

Part attributes

As I think through using multiple part names to indicate part state, I'm becoming worried that it'll get quite complex.

The problem is that a MenuButton knows what values of horizontalAlign are valid. A component using a MenuButton instance in its shadow does not — but it's that outer component that will need to stick a part like horizontal-align-left on the MenuButton instance. That means the outer component needs to track the current value of the menu button's horizontalAlign property ("left", etc.), munge it to some part variation (horizontal-align-left, etc.), and manage that on the part. That's non-trivial JS that needs to be written for any parts with styling that might depend on component or part state. It could be made to work, but will be cumbersome.

The reason I suggested considering something involving attributes is that native HTML elements already reflect their inner state as attributes for styling purposes. It'd be reasonable to ask component authors to do the same for those properties that might be implicated in styling.

We can easily extend our MenuButton component to reflect a horizontal-align="left" attribute on itself when the underlying horizontalAlign property changes. If the MenuButton is being using directly in light DOM, then style rules can be written to target that attribute value. If the MenuButton is being used as a part, the page author can write style rules that target the part name and the attribute value. That is, styling something directly or as a part would be the same.

I think there would be ergonomic advantages to [attr="value"] if you were able to set attributes indiviually as you can on a HTML element but if you're setting them inside part-attribute="attr=value" then there's very little win on top of just doing part="attr=value" which gives you a part named attr=value.

My suggestion was not to let someone set attributes inside part-attribute. Rather, the part-attribute would give a, say, space-delimited list of part attributes that the component author wants to expose to the outside.

Example: Suppose a MenuButton has two properties/attributes that might be interesting to people styling the component: horizontalAlign and opened. Someone using the menu button as a part could write:

<menu-button part="menu-button" part-attributes="horizontal-align opened">

Or, if they only want to let someone style the "opened" attribute on the part, they write part-attributes="opened". That is, part-attributes means something like, "attributes someone styling this part might want to target". Another name might be styleable-attributes.

The MenuButton instance then reflects the current state of the horizontalAlign and opened properties as attributes. Someone using a menu button in light DOM can write:

menu-button[horizontal-align="left"] { ... }

And someone targeting a MenuButton as a part would write:

my-component::part(menu-button)[horizontal-align="left"] { ... }

That is, it's essentially the same syntax.

• It's also the same work for the person writing MenuButton, who knows the component best anyway.
• This is consistent with how someone writes CSS targeting native element states via attributes.
• People using ::part() could potentially use the full range of attribute selectors ([attr~=value], etc.), not just existence/non-existence.
• It's less work for the person using MenuButton as a part. That person just needs to know whether they want to let someone write styles like the above example, and they can capture their decision in markup. They don't need to think about values of horizontal-align or add/remove part values dynamically in JS.

We also need to think about forwarding from deeper shadow-trees. Would we need a way to forward and rename attributes?

FWIW, I believe that, if the person exposing a part deems it reasonable to expose an attribute on that part for styling, that other component authors further up the chain would probably be fine leaving such flexibility in place as they forward the part. It's zero additional work for them. That is, I don't think someone forwarding a part will need to narrow the set of attributes available for styling.

Apologies if the examples are abstruse. The number 1 request we get from potential users of our library is whether they can style the components in CSS, so we're interested in making this easy for those users. If it'd be helpful to talk through any of this, I'll make myself available for a chat.

[fergald]

Thanks for all that info. The part-attributes stuff makes more sense as you've clarified it. I have some concerns about it exposing more implementation details than is desirable, e.g. if I write a component and it contains some sub-component and I export some of that sub-components parts, then I have no control over the exported attribute names and values, they may be inconsistent with the names and values I use in the parent component and if I swap out that sub-component for an entirely different implementation, they may have an entirely different set of names of values. So there would be no way to ensure a stable API given different implementations (whereas part renaming does give us that even when exposing parts that are not controlled by the parent component's author).

All that said, perfect is the enemy of good. The value of being able to do this at all seems high and it also seems unlikely that we would ever go as far as adding something to allow transforming attribute names and values to allow a stable API to be presented in cases like these.

The problem is that a MenuButton knows what values of horizontalAlign are valid. A component using a MenuButton instance in its shadow does not — but it's that outer component that will need to stick a part like horizontal-align-left on the MenuButton instance. That means the outer component needs to track the current value of the menu button's horizontalAlign property ("left", etc.), munge it to some part variation (horizontal-align-left, etc.), and manage that on the part. That's non-trivial JS that needs to be written for any parts with styling that might depend on component or part state. It could be made to work, but will be cumbersome.

I'm not sure I follow this example. The containing component would not put a part= on the MenuButton, it would put exportparts=. E.g.

<style>.bar::part(button-foo) { ... }</style>
<custom-elem class="bar">
  # shadow
  <menu-button exportparts="foo: button-foo">
  # shadow
    <div part="foo">...</div>
  </menu-button>
</custom-elem>

If we added wildcard exports then this would change to be

...
  <menu-button exportparts="foo: button-foo attr-*">
...

only the inner component would have to worry about tracking state and munging things to look like part="foo attr-horizontal-align=left".

It's still hacky. I think part-attributes= makes a lot of sense but I'm also interested in how far we can get without it, since we still haven't got the basic part= and exportparts= enabled in any browser yet, so adding this seems a long way off.

[caridy]

I always thought that this will be possible only via CSS tokens/states (WICG/webcomponents#738), where the possible states of your component are part of the public API of it, and using them in conjunction with parts seems to be enough for such styling, e.g.:

my-tab-component::part(tab-button) {
  color: black;
}

my-tab-component:state(selected)::part(tab-button) {
  color: red;
}

@tabatkins @domenic can you confirm that this compounding will be possible?

@JanMiksovsky this, of course, is not equivalent to what you're asking because it is not really the state of the part, but the state of the component that exposes the part, but I think it will cover a lot of ground. Also, consider that we haven't really work on the css state proposal, we need a formal proposal first.

[JanMiksovsky]

@caridy Yes, this would be helped by representing component state via custom pseudo-classes. I referenced those in the original post, but I wasn't sure whether those were on a track to happen sooner than basic ::part support.

Note also that I'm talking about letting parts, not just overall components, that have state. In the tabs example, the overall tabs doesn't have the selected state, the individual tab buttons have a selected state. In other words, rather than something like:

my-tab-component:state(selected)::part(tab-button) {}

I'm more concerned about supporting something like

my-tab-component::part(tab-button):state(selected) {}

where the state applies to the part instead of the component.

The containing component would not put a part= on the MenuButton, it would put exportparts=.

@fergald You're correct, thank you for catching that.

I thought it might also be interesting to share some further experimentation here. We've created a working styled variation of our Elix Tabs component that uses CSS parts.

• Stock Tabs example
• Demo of styled tabs using parts. (Requires current Chrome Canary with the Experimental Web Platform Features flag turned on.)

The second demo is the same tabs component as the first, styled using CSS parts. (The only exception is the crossfade effect on the pages, which we achieve by other means not relevant to this discussion.)

We achieved this style tabs demo through a riff on @tabatkins's idea to use multiple parts. Here, we apply one part name ("proxy") to unselected tabs, and a different part name ("proxy-selected") to the selected tab. (Apologies for the ambiguous "proxy" term instead of "tab button" in the demo CSS, but the base class for our Tabs component is actually an extremely general component called Explorer that is used for much more than just tabs.) Using different part names like that is obviously cumbersome, but works today, and gives us a glimpse of what we'd like to let our component customers achieve through CSS parts.

Although there's still a long road ahead, we're quite excited by being able to do this at all. The stock Tabs (elix-tabs) element looks mundane but provides a large number of features that may not be obvious: keyboard support (via arrow keys while a tab button is selected), ARIA, resilience if tabs are added/removed at runtime, etc. It will be fantastic if someone can receive all those benefits and still get the visual aesthetic they want through CSS.

That said, we remain convinced that some form of per-part styling will be necessary to let customers style our components as they would like. That could take the form of:

1. Support for multiple parts as @tabatkins suggested above.
2. Support for something like part-attributes that I proposed above.
3. Support for custom pseudo-classes and the flexibility to specify those after a ::part.

[caridy]

@JanMiksovsky I don't think my-tab-component::part(tab-button):state(selected) will fly, that represents a loosely API on the my-tab-component, since any changes in the component representing the tab-button part will automatically affect your component.

[JanMiksovsky]

@caridy I think that's unavoidable — and also fine. I'm starting from the assumptions that:

1. Devs want to build components from smaller subcomponents.
2. Components (including subcomponents) may have idiosyncratic state, i.e., conditions that are not universally applicable or meaningful for all components.
3. Page authors want to style components, including those portions provided by subcomponents, and including styling for unique states at both the component and subcomponent level.

So if I build components from subcomponents, then I also take on both the risk and opportunity of being able to swap out those subcomponents for better ones in the future. That might break someone's careful styling of my component that assumes the old subcomponent.

That's unfortunate, but to me no different than the possibility that future work might force me to make a breaking change in a component's JS API. And the very existence of a part at all implies a contract that might get broken. If I add a part, I can't guarantee to the world that I'm never going to take that part away.

I would think devs could approach CSS support exactly like JS support: try hard not break contracts, but allow for that possibility, and use conventions like semver and documentation to signal when contracts are getting broken.

[tabatkins]

JS also has a lot of tools to help authors hide things (closure-based state, wrapper objects that expose a more minimal API, etc). HTML and CSS don't; they're fundamentally simpler languages in this regard.

We still don't want to expose anything from the component that the component author isn't explicitly deciding to expose (or at least, explicitly wildcarding, with the knowledge that what they're doing is a little dangerous). Implicitly exposing extra data from subelements breaks encapsulation in an important way here.

[domenic]

@JanMiksovsky thank you for your detailed post at #3431 (comment) , and apologies for taking a while to process it. I think I'm not fully understanding something though, which is why in your component libraries there are so many parts-with-states.

If you look at built-in HTML elements with UA shadow DOM (or other complex internals) today, they all use shadow DOM for encapsulation. The encapsulation is complete enough that the parts themselves don't really have any state; instead that gets bubbled up to the host element. Any case where there's a complicated-enough sub-element that has its own potential states ends up being done through light DOM, not shadow DOM.

So for example, you have a my-tabs-component, but from what I can gather in the OP, you have put all interesting sub-parts inside the shadow DOM. This means you have to re-expose them as ::parts, and thus leads you to getting into trouble with sub-states and so on.

But this isn't how we would design a built-in element. There, the interesting sub-parts would be in the light DOM, e.g. something like

<tabs>
  <tab>
    <tabbutton>One</tabbutton>
    Page One
  </tab>
  <tab>
    <tabbutton>Two</tabbutton>
    Page Two
  </tab>
  <tab>
    <tabbutton>Three</tabbutton>
    Page Three
  </tab>
</tabs>

Indeed, I see you even have an example of that later down in your own docs, with "Custom content in default tab buttons"!

In other words, parts make sense for things that are internal parts of your main component, like ::backdrop, ::cue, ::placeholder, ::marker, ::-webkit-slider-thumb, etc. In those cases, the state reflects up to the main element (e.g. input:placeholder-shown, or a fictional dialog:backdrop-shown or similar). But if you have something like a tab button, which is its own first-class object with its own states, then those things should probably be in the light DOM, not hidden inside the shadow DOM. And if they're in the light DOM, they don't need to indirect through parts in this way.

In general one rule of thumb I might come up with is that any time there can be an arbitrary number of the sub-control, it's probably first-class enough to need light DOM exposure. If the sub-control is 1:1 with the main custom element, then maybe it's just a part.

With this framing in mind, do you have any other examples from your 26+21+6 components where it's a more clear-cut case of the sub-part having its own state, that run into the issue described in the OP? Because the specific OP issue doesn't make sense to me anymore now that I look at this in more detail. Especially seeing how you explicitly encourage users in your docs to have light DOM elixir-tab-button elements which could just be addressed with normal CSS selectors and not need ::part to select them.

[kevinpschaaf]

@domenic I agree that for many leafy "widgets" along the lines that the UA ships, composition via light DOM is preferable for the reasons you list. There are probably still interesting cases to investigate that still expose this issue -- perhaps the "carousel" example is a good one to study:

<my-carousel>
  <img src="a.png">
  <img src="b.png">
  <img src="c.png">
</my-carousel>

In its shadow DOM, it might create a "dot" affordance in the shadow DOM for each light DOM item in the carousel, and swiping images changes the selected dot. I could see wanting to allow style ::part(dot) and ::part(dot):state(selected) separately.