[css-shadow-parts] Unifying ::part() and ::--foo

[tabatkins]

tldr: We should allow part names to also be selected as full custom pseudo-elements names, a la my-component::--heading in addition to my-component::part(heading).

---

In the Web Components virtual f2f today, we discussed custom pseudo-classes. In the thread about :state(foo) vs :--foo syntax, Maciej brought up the reasonable point that switching away from :state() to :--foo, but leaving parts as ::part(), is inconsistent.

I explained the reason behind maintaining ::part(): due to CSS's bad syntax choices in the past, pseudo-element syntax implicitly contains a combinator, moving the subject of the selector into the element's "pseudo children"; as a result, you can't stack pseudo-elements to apply multiple conditions to a single pseudo-element. However, we want to allow that for parts - we want a calendar widget to be able to expose day elements for styling with something like part="day weekend saturday week-1 us-holiday", and let stylesheets select on a combination of those qualities, like ::part(day weekend us-holiday)

However, Maciej's point is still valid! Also, people have wanted ::--foo syntax, to mirror normal pseudo-elements, and things like UA pseudo-elements (::-webkit-scrollbar-thumb, for example).

Jan's idea was to unify these - allow parts to be selected either with ::part(foo) or with ::--foo; if you only need to select on one property, you can use the more direct form, but ::part() remains if you have more complex selecting needs. This received general approval in the call, and I think it's a good idea personally. General thoughts?

---

I think there's one important detail to decide, which is how to handle existing part='' content. In general, CSSWG has made the decision that dashed-idents should be used consistently thruout APIs: you reference the --foo custom property with var(--foo), not var(foo), etc. In other words, the -- is part of the name, not a context-specific indicator of custom-ness.

Currently, tho, part='' allows any ident, not just dashed-idents. How should we deal with this? I see a few options:

1. (I don't like this, it's bad, but for completeness:) part is unchanged. If you define part="foo", you can reference it as ::part(foo) or ::--foo. In other words, the -- is a context-specific indicator of custom-ness, but is not used when defining it, or referencing in ::part(). (Note: if you said part="--foo", it would be referenceable as ::part(--foo)or::----foo`.)

   This is backwards-compatible with existing code, but breaks consistency with how dashed-ident features are used everywhere else in CSS, both currently and planned. The component author doesn't make a choice on how to expose things, but the component user is presented with two fairly different names to refer to.

2. part is unchanged. If you define a part as a dashed-ident, it can be referred to as a top-level pseudo-element. That is, given part="foo --bar", you can use ::part(foo), ::part(--bar), or ::--bar validly. ::--foo will not match, nor will ::foo.

   This is backwards-compatible with existing code, and consistent with CSS design principles for dashed-idents. However, it imposes a choice on component authors of whether they want to expose parts as top-level pseudos or only within ::part(). (There might be a good reason to make this distinction? Unsure, but I suspect not.)

3. We restrict part to only allow dashed-idents. part="foo --bar" only defines one part name, --bar, which can be referenced as either ::part(--bar) or ::--bar. (The "foo" is ignored, as part of our forward-compatible error handling that silently drops things that aren't understood.)

   This is not backwards-compatible; virtually all existing content would become invalid and stop defining parts. However, it means there's no choice on the component author's side, and the component user has a closer relationship in the two syntaxes.

I slightly lean toward 3, but I'm unsure how much back-compat pain we want to take on. I'm fine with 2 if it's preferred by others. I'll fight against 1, it's terrible.

[plinss]

I'm in favor of this change and also favor 3. I was considering something along these lines as a migration from the current syntax to ::--foo. Hopefully the :part() syntax can eventually be deprecated.

I still have issues with the current design of shadow parts using multiple part names as an ersatz class/pseudo-class mechanism. I'd much rather see us fix selectors, e.g. your example could be ::--day:--weekend:--us-holiday (using custom state) or possibly something like ::--day(weekend us-holiday), but in that case 'weekend' and 'us-holiday' should probably not be part names but an additional property of the part.

I don't have an issue with parts having multiple names, but that should only mean it can be selected as either of those names, e.g. <custom-day part="--day --weekend"> matches both ::--day and ::--weekend.

[JanMiksovsky]

Credit where credit's due: I think the idea to unify these was from @justinfagnani.

[tabatkins]

Hopefully the :part() syntax can eventually be deprecated.
[...]
I'd much rather see us fix selectors, e.g. your example could be ::--day:--weekend:--us-holiday (using custom state)

I disagree.

First, a more abstract objection: I don't think the tagname/classname distinction we currently have in the DOM is a useful distinction. It's something we inherited from DOM, but there's no meaningful difference between the two semantically; we even invented two "pretend I don't have a tagname" elements (div and span) to allow authors to supply their own semantic fully thru classes. The only thing tagnames meaningfully do is trigger browser-default behavior (a acts like a link, etc), but as far as CSS is concerned that's more or less a non-issue, and even then HTML is littered with exceptions (like all the various inputs clustered under a single input name despite varying behavior and semantics).

So I don't think we should be trying to introduce the same distinction for custom elements. Elements have a set of idents with class-like semantics; there's no need for a tagname-like semantic, and forcing authors to decide which of their several possible idents qualify as "most tagname-like" is a decision we shouldn't force authors to make. We want to offer a tagname-like syntax for convenience, nothing more.

Second, a more concrete objection: having a custom element expose its part semantics as pseudo-classes clashes with the existing custom pseudo-class proposal.

As I discussed in #7, I've come to believe that custom elements are indeed the most appropriate place in the DOM to expose custom pseudo-classes; in particular, I think there is no need to add them to arbitrary elements in the light dom. Custom Elements have their own, component-controlled semantics that need to be deployed as a separate namespace from the author-level semantic (classnames), so a pseudo-class with a distinct syntax space works out fine.

Exposed parts hit the same conflict: the part itself might be a custom element, which exposes its own custom pseudo-classes. The outer component already has a place to indicate class-like semantics on its elements, in the form of the part name; merging the two means there can be clashes between two not-necessarily-cooperating elements, same as a custom element exposing its states by manipulating its host's class attribute.

(In this, I am assuming that the part's custom pseudo-classes will be available for matching, same as most UA-defined pseudo-classes are. I don't think this is an encapsulation break.)

[tabatkins]

So I gave some more serious thought to what it would look like to let parts expose pseudo-classes as well, and yes, I'm pretty certain it introduces unresolveable problems.

So here's my sketch of how this all would work (forgive me for being somewhat stream-of-consciousness with it, tldr at the end):

First, a component can, itself, expose custom pseudo-classes declaring its state to the consumer of the component. This uses the API we're already talking about, no elaboration needed here.

Then, the component can expose parts of itself as pseudo-elements. Since our current concept of "part names" are class-like, but the pseudo-element syntax is restricted to not allow that semantic, we change things up a bit - custom elements can just expose one or more ::part pseudo-elements, and can add pseudo-classes to give more detail. So a calendar widget's days would all be ::part:--day, and could be further selected with ::part:--day:--weekend:--holiday for specific styling.

(If we allow the author to denote one of the keywords as the "name" of the pseudo, so the user could instead write ::--day:--weekend:--holiday, this doesn't materially change my analysis, so without loss of generality, let's continue to assume this doesn't happen and you only get ::part.)

But the part could itself be a custom element, which can expose both (a) its own pseudo-classes, and (b) its own parts.

If the inner component's pseudo-classes are automatically exposed to users of the outer components, we have an obvious potential for clashes, causing upgrade hazards we've tried hard to avoid; the <x-day> component might expose a :--holiday pseudo-class of its own, in a way that clashes with the calendar's desired usage. (For example, it might assume US holidays, while the calendar is internationalized and can do different countries.)

If the inner component's pseudo-classes are not automatically exposed, but rather have to be forwarded by the outer component, this is avoided, but it means more work for the component author: you can't just use a <cool-checkbox> component as a part and be done; instead you have to manually forward all the form-relevant pseudo-classes the element might expose. We don't want to allow wildcard forwarding, for the same reason we don't allow that for part names without a guarding prefix: it reintroduces the possibility of clashes.

But that's not all, the inner component can also have parts to expose, which, per our existing resolutions, need to be explicitly forwarded as well. So the outer component has to have a separate mechanism to filter/forward the parts. But now we have an interesting question: how? By the pseudo-classes it exposes, presumably? Or does it distinguish between the (external) part-defined pseudo-classes and the (internal) component-defined ones, and only filter on the former?

And then how do you decide which of the forwarded part's pseudo-classes should be exposed? Filtering is necessary at every level, after all; there's no good reason you should be able to filter your own parts but not any forwarded parts. Do we need a third forwarding mechanism to handle those? How, exactly, do we identify which forwarded parts are having their pseudoclasses filtered? The only way to refer to them is by their pseudo-classes, after all; this isn't like our own parts, where the element being filtered is the one we are adding the attributes to. So instead we're now dealing with filtering sets of forwarded parts, and have to deal with single parts showing up in multiple such sets and having clashing forwarding advice, too.

(Luckily we don't recurse further; any components nested further within the inner component have already been forwarded and filtered by the inner component, and we just have to handle its results.)

---

So yeah, ultimately the issue is that we're collapsing levels, something which is notoriously fraught. Part names and component pseudo-classes are distinct namespaces because they're controlled by different authors, but if we push them into the same namespace, avoiding clashes becomes a lot more complicated, to the point that I don't think authors can reasonably navigate it.

So I'm pretty strongly still of the opinion that part names and custom pseudo-classes, despite their partial overlap in semantics, should be kept separate. And that custom pseudo-classes should be exposed on parts by default, without any filtering mechanism.

[ExE-Boss]

(@tabatkins #4900 (comment))

As I discussed in #7, I've come to believe that custom elements are indeed the most appropriate place in the DOM to expose custom pseudo-classes; in particular, I think there is no need to add them to arbitrary elements in the light dom. Custom Elements have their own, component-controlled semantics that need to be deployed as a separate namespace from the author-level semantic (classnames), so a pseudo-class with a distinct syntax space works out fine.

I think you mean WICG/custom-state-pseudo-class#7.

[othermaciej]

Now that CSS WG has resolved to rename :state(foo) to :--foo, please make this corresponding rename sooner rather than later.

It looks like the conversation wandered to many tangentially related things, but the crux of this issue is renaming ::part(foo) to ::--foo for consistency with the :state change. It's weird for one of these features to use a name and the other to use a -- prefix, since they are meant to be used in tandem.

[justinfagnani]

The conversation has some critical points though: This change is not a simple rename. There is no custom-pseudo-element equivalent to ::part(foo bar) or ::part(foo:--bar). I definitely have written elements with multiple part names that are intended to be used in combination like ::part(foo bar). We need to keep ::part() to preserve those use cases. Adding ::--foo for simple cases is fine.

[othermaciej]

If that’s the case, it’s sad that consistency is not possible, and that impossibility of consistency was not really considered when resolving to do the :state rename.

[tabatkins]

@othermaciej We did consider that. The initial post in this issue is the proposal as it stands - you should be able to match a part name like "--foo" as ::--foo. We need to preserve ::part() as well for the specific purpose of matching an element based on multiple names at once, which is otherwise impossible (as an unfortunate side-effect of how pseudo-element syntax works).

There's an open design question in the OP; opinions would be appreciated!

[othermaciej]

Having two names for the same thing is kind of lame. I wonder if ::--(foo bar) would work for the complex cases?

[web-padawan]

As a library maintainer, I find the new syntax questionable in terms of developer experience.

::part(form-field):state(pristine)

👍 human friendly
👍 self-explanatory
👎 more verbose

::--form-field:--pristine

👎 confusing
👍 somewhat BEM-ish
👍 fewer bytes

Off-topic: what if we make it even more BEM-ish? 🤔

::__form-field:--pristine

[tabatkins]

I wonder if ::--(foo bar) would work for the complex cases?

Hmm, it would work parsing-wise — that's a --() function, which is allowed by Syntax.

It looks a little clunky to me, but that might be a kneejerk. I suppose I'm not opposed to it. Is that something you want to champion, then?

---

@web-padawan: Note how, if these were built-in pseudos, you'd spell them ::form-field:pristine. Doing ::--form-field:--pristine keeps us as close to built-ins as possible without polluting the built-in namespace.

[othermaciej]

Is that something you want to champion, then?

I don't know. It looks weird to me, but all the colon/dash prefixed things look weird to me, so that doesn't mean much. I do think it would be nice if we could avoid two aliases for the same thing.

Side note: is it useful to do what ::part(foo bar:baz) does for custom parts for built-in pseudo-elements? I could totally imagine a native date picking exposing parts similar to what you had for your custom calendar, but it would apparently have no way to solve the same problem. If so, perhaps what's really missing is a generic CSS syntax for pseudo-element multi matching?