mention restriction about nested rules starting with an identifier

[mayank99]

the latest css nesting spec disallows this for technical reasons:

.foo {
  span {
    color: hotpink;
  }
}

when i first upgraded to postcss-nesting 11.0, i was under the impression that such syntax would be supported, because those technical limitations do not exist outside browsers. so i was very surprised when #861 was released in 11.2.1 and my styles broke.

this note will help avoid such unexpected surprises for users of postcss-nesting.

[romainmenke]

Hi @mayank99, thank you for contributing!

---

when i first upgraded to postcss-nesting 11.0, i was under the impression that such syntax would be supported, because those technical limitations do not exist outside browsers

The readme starts with a note that this plugin follows the specification.
Is there anything in the docs that gives the impression that this plugin aims to do more than what browsers can do?

It must have also given a warning to make it clear that this was not supported.
Was there no such warning?

---

I am a bit hesitant to add this to the readme for multiple reasons :

• we detect this pattern and emit an actionable warning.
• the specification is still in flux and the CSSWG really wants to get rid of this restriction.
• we already document that we follow the specification and we don't want to document the specification in detail.

We do sometimes have docs about such aspects but mostly to avoid confusion when the "transpiled css" is not what people might expect :

• https://github.com/csstools/postcss-plugins/blob/main/plugins/postcss-custom-media/README.md#true-and-false
• https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-cascade-layers#how-it-works

[mayank99]

Was there no such warning?

@romainmenke You're right, there is a warning. I think I missed that, because the build still passes.

the specification is still in flux and the CSSWG really wants to get rid of this restriction.

hmm, based on recent discussions, i thought the nesting spec was mostly finalized. Maybe not.

we already document that we follow the specification and we don't want to document the specification in detail.

i agree, it does not make sense to document it in detail, but this does directly affect the use of the plugin. plus, this nuance is very easy to miss in the spec.

would you accept the PR if i trim it down to just a couple lines?

[romainmenke]

would you accept the PR if i trim it down to just a couple lines?

Hehe no, the issue is not that it is long or short :)

It is just that I am hesitant to take on the role of explaining and documenting the feature itself. Especially given the state of the feature/specification and the complexity of the feature.

I think it might make sense to add some extra docs up until there are good docs on MDN and enough blog posts explaining this.

[romainmenke]

@mayank99 I've made a few tweaks and copied it over to the readme template.

• included the warning so that people can find this when they google the warning text
• mentions both types of selectors where this issue will surface

What do you think?

[mayank99]

included the warning so that people can find this when they google the warning text

This makes perfect sense! Including the warning makes it even more relevant to this project (rather than simply explaining the spec), and users know what to expect before installing the plugin.

I think it might make sense to add some extra docs up until there are good docs on MDN and enough blog posts explaining this.

Exactly. I think docs should actively try to educate on the concepts that lie at the boundaries of what the code/package is designed for, or at the very least provide a pathway for the user to learn. In the future when there are better resources on this topic, the note could be removed and a link might suffice.

---

Only suggestion I have is to pin to the current version of the spec, in case the link to "Example 4" changes.

[romainmenke]

Thank you for this @mayank99 🎉

[mayank99]

Thank you for merging the PR! I know it can be a maintenance burden, so it is extra appreciated 💜