the new rule for :matches() introduces the possibility that different ways of matching a complex selector (i.e., pairings between elements and the compound selectors in the complex selector) have different specificity

@dbaron, could you please provide an example of this possibility?

My understanding so far is that :matches() is basically just kind of syntactic sugar for shortening long lists of selectors that have common parts. So, when a browser checks an element against something like .menu > :matches(a, .current) > .icon, under the hood it does the same work as for checking the same element against .menu > a > .icon, .menu > .current > .icon. Yes, it can possibly introduce performance issues for complex selectors with several :matches(), when the browser would have to check the element against all the combinations of their arguments (so the numbers of the variants would multiply), but it still would be in fact just a very long list of the usual selectors, at least one of which is the most specific. Am I wrong?

Also, given that :matches() has already been implemented in WebKit for about a year and a half, maybe they can provide some feedback about how they dealt with these issues?

Yes, :matches() is solely syntactic sugar (tho with complex selector arguments, the expanded form can get very verbose - try to expand out :matches(.a .b .c, .d .e .f) fully and correctly).

Yes, :matches() is solely syntactic sugar (tho with complex selector arguments, the expanded form can get very verbose - try to expand out :matches(.a .b .c, .d .e .f) fully and correctly).

This example isn't very verbose. Consider .a .b .c :matches(.d .e .f), which can be very verbose.

@SelenIT

could you please provide an example of this possibility?

If I understand correctly, an example could be

<div id="a"></div>
<div id="b">
  <div id="c"></div>
  <div id="d" class="foo">
    <span id="e">Styles are being assigned to this element</span>
  </div>
</div>

:matches(#a, *) + :matches(.foo, *) span

An implementation could detect that

1. #e matches span with specificity (0,0,1).
2. #d matches both .foo and *, so it matches :matches(.foo, *) with specificity (0,1,0).
3. #c matches * but not #a, so it matches :matches(#a, *) with specificity (0,0,0).

So the whole selector is matched with specificity (0,0,0)+(0,1,0)+(0,0,1) = (0,1,1)

However, there is another way to match the selector:

1. #e matches span with specificity (0,0,1).
2. #b matches * but not .foo, so it matches :matches(.foo, *) with specificity (0,0,0).
3. #a matches both * #a and *, so it matches :matches(#a, *) with specificity (1,0,0).

So the whole selector is matched with specificity (1,0,0)+(0,0,0)+(0,0,1) = (1,0,1)

It would be bad if different implementations calculated the specificity of :matches on different elements, because this could affect the total specificity. :nth-* are also affected:

the specificity of an :nth-child(), :nth-last-child(), :nth-of-type(), or :nth-last-of-type() selector is the specificity of the pseudo class itself (counting as one pseudo-class selector) plus the specificity of its selector list argument (if any)

I see various possible solutions:

• Properly specify on which elements the pseudo-classes are calculated, e.g. the ones that maximize the total specificity. This might have performance problems.
• Ignore the selector list argument and let the specificity be (0,1,0) like a normal pseudo-class. :-moz-any and :-webkit-any seem to behave like this.
• Remove :something/:is and define the specificity of :matches to be (0,0,0).

@Loirooriol, I don’t see this ambiguity in the spec. Since the spec for :matches() specificity says

The full selector’s specificity is equivalent to expanding out all the combinations in full

this example will be expanded as

#a + .foo span, #a + * span, * + .foo span, * + * span { ... }

and by the rules of the selectors list specificity, its specificity will be the largest one of the individual selectors in the list that match the element, in this example it would be (1, 0, 1) of #a + * span. There is only one way to expand :matches() into selector list, and any selector list has only one maximum specificity value of its parts (even if several parts have the same specificity), so there is no place for the ambiguity to occur.

Do I miss something?

Yes, with that interpretation the specificity is not ambiguous, but as dbaron said, the definition "isn't worded in a particularly clear way". And may not be the best choice if it has performance problems (expanding :matches can produce exponentially-long selectors).

Attempted to address the clarity issue in 88b91c0; the specificity rules were written with only compound selectors in mind, and so for complex arguments the existing prose indeed didn't make sense. I don't think it's perfect now, but should be better.

That doesn't address the perf concerns, though. @Loirooriol's comment #1027 (comment) summarizes some of the options; I'll repeat them here and add the missing one:

• Specificity of :matches() is the specificity of the most specific selector that can match. This is what the spec says now, and is the only logical conclusion of treating :matches() as syntactic sugar to the extent that it can be (i.e. when it contains compound selectors only).
• Specificity of :matches() is the specificity of any other pseudo-class. This is in conflict with how :not() works already, and also means that S:nth-child(n) and :nth-child(n of S) have different specificities, which is imho not reasonable. (They are functionally different, but have the same weight of meaning.)
• Specificity of :matches() is zero. Same problems as (0,1,0).
• Specificity of :matches() is that of its most specific argument. We lose the equivalency of :matches(a,b,c) and a,b,c, but we maintain consistency with :not(), and S:nth-child(n) & :nth-child(n of S) maintain equivalent specificities.

The last option looks promising because the specificity of the selector can be determined without expanding it, but would it play a significant role in practice? If checking for selector matching would require expanding it anyway, will calculating the specificity dynamically necessary need any overhead in terms of performance?

Maybe @victoriasu can provide some details from the implementer's perspective?

@fantasai While definitely useful, I think 88b91c0 still does not clarify that the "calculating a selector’s specificity" algorithm requires an element, and which element is used for the argument of :matches and friends. But I guess this can wait until this issue is resolved.

And thanks for adding the missing option, I thought I included it but it seems I forgot. It may be the nicest one. I'm not an expert but I expect that matching :matches without expanding it should be feasible, @SelenIT. Otherwise, I think it should be confined to the snapshot profile.

@SelenIT I am planning on expanding :matches for the specificity. Webkit appears to also use the expanded specificity from what I see when running: https://jsfiddle.net/victoriaytsu/vwsfsfr6/

[:matches(.a .b .c, .d .e .f)] isn't very verbose. Consider .a .b .c :matches(.d .e .f), which can be very verbose.

Oh shoot, you're right, I meant to write :matches(.a, .b, .c):matches(.d, .e, .f), not a single comma-separated one. (As written, my example is equivalent to a plain .a .b .c, .d .e .f selector list.)

As far as I understand, we have 2 implementations of :matches() per the existing spec (option 1 from the above list) since yesterday, one shipped and one experimental behind the flag. (Well done, @victoriasu!)

Is the way of calculating its specificity still subject to change?

So at first glance at the Chromium's code it seems that very few expansions are allowed:
https://chromium-review.googlesource.com/c/chromium/src/+/879982/15/third_party/WebKit/Source/core/css/CSSSelectorList.cpp#165

Effectively https://jsfiddle.net/u9q1ogc7/ demonstrates the failure. Text should be green.

I think :matches matching should not use expansion and the specificity should be fixed.

FWIW, @Loirooriol 's previous comment led to bug 817835.

Today @emilio and I filed bug 842157 about how Chromium's expansion approach produces incorrect results, e.g., on this test (which WebKit passes). :matches() with combinators inside it fundamentally allows branchy selectors that can't be written straightforwardly in pre-:matches() CSS syntax.

So this seems reasonable to me. Slightly unfortunate, but reasonable. Agenda+ing for confirmation.

If, like me, you had trouble following how :matches should work in this thread, consider the following CSS:

head ~ :matches(html > *) {}

If I understand correctly, that selector should match body, and it should not be equivalent to the following expansion:

head ~ html > * { /* nonsense */ }

Chrome (and postcss-selector-matches) have incorrectly interpreted :matches to follow the later behavior.

Anyway, this is just here to save people like me an hour or so of processing time. And if I misunderstood, please correct me.

@jonathantneal, I agree with your understanding! This selector says "all following siblings of the head element that are also children of the html element", i.e. this selector is equivalent to

html > head ~ * {
  /* targeting elements that are siblings of `head` _and_ children of `html`
     implies that `head` itself must be child of `html`, too */
 }

However, your example made me realize that expanding the brackets of :matches() can be rather non-trivial when both nesting and sibling combinators come into play. Before, I only considered simpler nesting examples like

:matches(.a .b .c):matches(.d .e) { ... }

(based on examples above) which would be expanded out as

.a .b .d .c.e,
.a .b.d .c.e,
.a .d .b .c.e,
.a.d .b .c.e.
.d .a .b .c.e {
   /* target elements with both 'c' and 'e' classes inside '.a .b' and '.d' in the same time */
}

which becomes rather verbose, but still easier to figure out.

So some implementation feedback from the WebKit team would be really appreciated!

Considering the selector in the test from the @dbaron's comment above: if there were classes instead of type selectors there

.h3 ~ :matches(.h1 ~ p.test):matches(.h2 ~ p.test) { ... }

then it would be expanded as

.h1 ~ .h2 ~ .h3 ~ p.test,
.h1 ~ .h3 ~ .h2 ~ p.test,
.h2 ~ .h1 ~ .h3 ~ p.test,
.h2 ~ .h3 ~ .h1 ~ p.test,
.h3 ~ .h1 ~ .h2 ~ p.test,
.h3 ~ .h2 ~ .h1 ~ p.test,
.h1.h2 ~ .h3 ~ p.test,
.h1.h3 ~ .h2 ~ p.test,
.h2.h3 ~ .h1 ~ p.test,
.h1 ~ .h2.h3 ~ p.test,
.h2 ~ .h1.h3 ~ p.test,
.h3 ~ .h1.h2 ~ p.test,
.h1.h2.h3 ~ p.test { /* p.test preceded by all .h1, .h2, and .h3 in any possible order */ }

With type selectors (as in the original example) only the first 6 combinations make sense, so the equivalent expanded result can be shorter.

Correct all around; expanding :matches() out to the full set of equivalent :matches()-less selectors can result in a combinatorial explosion of selectors. This is why Sass, which has a virtually-identical problem with its @extend rule, instead just heuristically determines the "most likely to be useful" selectors, and only expands into those.

html > head + :matches(html > head + body) is like html > head + body, but with what specificity?

The specificity of the :matches() pseudo-class is replaced by the specificity of its argument.

suggests specificity (0,0,5)

Thus, a selector written with :matches() has equivalent specificity to the equivalent selector written without :matches()

suggests specificity (0,0,3), unless we consider the "equivalent selector written without :matches()" to mean html:not(:not(html)) > head:not(:not(head)) + body

The specificity of the :not() pseudo-class is replaced by the specificity of the most specific selector in its argument; thus it has the exact behavior of :not(:matches(argument)).

This appears to imply that the specificity of the :matches() pseudo-class is replaced by the specificity of the most specific selector in its argument, so html > head + :matches(body > head + html, *) is like html > head + * but with specificity (0,0,5).

The current spec defines that it has the specificity of the matched branch, exactly as if you'd fully expanded the :matches() away.

The proposal in this thread is that it instead has a fixed specificity, probably identical to :not(), so the selector would have [0,0,5] specificity.

The Working Group just discussed reconsider specificity rule for :matches(), and agreed to the following:

• RESOLVED: Make specificity of :not() :has() and :matches() not depend on matching

Don't forget about :nth-child and :nth-last-child.

OK, committed these changes to the ED:
https://drafts.csswg.org/selectors-4/
76eefbb

Anyone here want to take a stab at reviewing it to make sure a) I got it right b) I fixed all the points that needed fixing c) It's sufficiently clear? :)

Looks good.

Typo: extra ] in [hidden]]

Typo: '':matches'' should be '':matches()'', otherwise it's not linked.

Suggestion: link "complex selector" to https://drafts.csswg.org/selectors-4/#complex

:not has a different text than :matches and :nth-child, this may make people think their specificity is not calculated in the same way. Since the point is that the element doesn't matter, I would just use "whenever it matches any element" in all three cases.

I would also prefer if the specificity was defined with a properly clear algorithm. The current one can be ambiguous, e.g. in

people may think ID selectors inside :matches should also be counted, but it's only the "top-level" ones.

Something like this:

Given a selector s and an element e which is matched by s, the specificity of s in e is calculated as follows:

1. If s is a complex selector, return the absolute specificity of s.
2. Else, s is a selector list. Return the maximum among the absolute specificities of the selectors in the list that match e.

The absolute specificity of a selector s is calculated as follows:

1. If s is an universal selector, or a :where() pseudo-class selector, return (0,0,0).
2. If s is a type selector or a pseudo-element, return (0,0,1).
3. If s is a :matches(), :not(), or :has() pseudo-class selector, return the absolute specificity of its selector list argument.
4. If s is a :nth-child(), or :nth-last-child() pseudo-class selector, return (0,1,0) plus the absolute specificity of its selector list argument (if any).
5. If s is a class, attribute, or pseudo-class selector, return (0,1,0).
6. If s is an ID selector, return (1,0,0).
7. If s is a compound selector, return the sum of the absolute specificities of the simple selectors in s.
8. If s is a complex selector, return the sum of the absolute specificities of the compound selectors in s.
9. Else, s is a selector list. Return the maximum among the absolute specificities of the selectors in the list.

Doesn't the phrase "its most specific argument" (implying that this functional pseudo-class takes several arguments) technically contradict the phrase "a functional pseudo-class taking a selector list as its argument" from the definition (implying that the selector list as a whole is considered a single argument)? Maybe it would be better to reuse the phrase "the most specific complex selector in its selector list argument" in the definition of :matches(), for consistency with the definition of :nth-*-child(... of S) and with the section about the specificity calculation?

Oh dang, actually, I think I remember there was an earlier intent that we could use :matches() as an end-run around the terrible "a syntax error in one complex selector kills the whole sequence" behavior that Selectors is stuck with. As such, it should be clarified to take an <any-value>, then split on top-level commas, then parse each result as a <complex-selector> and just ignore invalid ones.

I'll open a different issue about this.

@tabatkins, should :matches()/:is() be the only selector with such behavior, or the idea is worth generalizing to all functional pseudo-classes whose argument can contain a selector list (:not(), :nth-/:nth-last-child(... of S), :has(), probably where(), maybe time-dimensional pseudo-classes)?

OK, I'm closing out this issue. @Loirooriol I didn't remove the specific examples in favor of "any element" because I think they help point out the unintuitive result that while em, #foo matching <em> has a specificity of 1 tag selector, :is(em, #foo) matching <em> has the specificity of 1 ID selector. Also, rewriting the whole section should have its own issue. :)

I am wondering now if we should have been choosing the least specific argument instead of the most specific one, though...