nesting : latest specification (#996)

* nesting : latest specification

* changelogs

* add docs for silence option and link to stylelint plugin

Author: romainmenke

plugin-packs/postcss-preset-env/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changes to PostCSS Preset Env
 
+### Unreleased (minor)
+
+- Add warning when using the deprecated `@nest` rule
+
 ### 8.4.2 (June 1, 2023)
 
 - Updated `@csstools/postcss-progressive-custom-properties` to `2.3.0` (minor)

plugin-packs/postcss-preset-env/test/basic.autoprefixer.expect.css

@@ -525,7 +525,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.autoprefixer.false.expect.css

@@ -525,7 +525,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ch38.expect.css

@@ -435,7 +435,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ch88-ff78-saf10.expect.css

@@ -432,7 +432,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ch88-ff78.expect.css

@@ -432,7 +432,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ch88-ff78.no-is-pseudo.expect.css

@@ -432,7 +432,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.css

@@ -402,7 +402,7 @@
 @custom-selector :--view-m [data-view-size=m];
 
 .view {
-	@nest :--view-m & {
+	:--view-m & {
 		background: red;
 	}
 }

plugin-packs/postcss-preset-env/test/basic.expect.css

@@ -542,7 +542,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ff49.expect.css

@@ -438,7 +438,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ff66.expect.css

@@ -433,7 +433,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.hebrew.expect.css

@@ -538,7 +538,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.ie10.expect.css

@@ -559,7 +559,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	-ms-flex-order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.nesting.false.expect.css

@@ -537,7 +537,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 }
 
 .view {
-	@nest :--view-m & {
+	[data-view-size=m] & {
 		background: red;
 	}
 }

plugin-packs/postcss-preset-env/test/basic.nesting.true.expect.css

@@ -410,7 +410,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.op_mini.expect.css

@@ -522,7 +522,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.preserve.false.expect.css

@@ -661,7 +661,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	-webkit-box-ordinal-group: NaN;

plugin-packs/postcss-preset-env/test/basic.preserve.true.expect.css

@@ -891,15 +891,15 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 :is([data-view-size=m]) .view {
 		background: red;
-}
+	}
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	-webkit-box-ordinal-group: NaN;

plugin-packs/postcss-preset-env/test/basic.safari15.expect.css

@@ -414,7 +414,7 @@
 
 :--view-m .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.stage0-ff49.expect.css

@@ -434,7 +434,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.stage0-ff66.expect.css

@@ -429,7 +429,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * calc(8 / 3 + calc(5 * 10)));

plugin-packs/postcss-preset-env/test/basic.stage0.expect.css

@@ -538,7 +538,7 @@ h1.test-custom-selectors:not(.does-not-exist), h2.test-custom-selectors:not(.doe
 
 [data-view-size=m] .view {
 		background: red;
-}
+	}
 
 .nested-calc {
 	order: calc(1 * (8 / 3 + (5 * 10)));

plugin-packs/postcss-preset-env/test/basic.vendors-1.expect.css

@@ -545,7 +545,7 @@
 @custom-selector :--view-m [data-view-size=m];
 
 .view {
-	@nest :--view-m & {
+	:--view-m & {
 		background: red;
 	}
 }

plugin-packs/postcss-preset-env/test/basic.vendors-2.expect.css

@@ -545,7 +545,7 @@
 @custom-selector :--view-m [data-view-size=m];
 
 .view {
-	@nest :--view-m & {
+	:--view-m & {
 		background: red;
 	}
 }

plugin-packs/postcss-preset-env/test/basic.vendors-3.expect.css

@@ -517,7 +517,7 @@
 @custom-selector :--view-m [data-view-size=m];
 
 .view {
-	@nest :--view-m & {
+	:--view-m & {
 		background: red;
 	}
 }

plugins/postcss-nesting/.tape.mjs

@@ -58,11 +58,20 @@ postcssTape(plugin)({
 			noIsPseudoSelector: true,
 		},
 	},
-	'at-rule': {
-		message: 'supports at-rule usage',
+	'at-nest': {
+		message: 'supports at-nest usage',
+		warnings: 64,
 	},
-	'at-rule:no-is-pseudo-selector': {
-		message: 'supports at-rule usage { noIsPseudoSelector: true }',
+	'at-nest:silent': {
+		message: 'supports at-nest usage { silenceAtNestWarning: true }',
+		warnings: 4,
+		options: {
+			silenceAtNestWarning: true,
+		}
+	},
+	'at-nest:no-is-pseudo-selector': {
+		message: 'supports at-nest usage { noIsPseudoSelector: true }',
+		warnings: 64,
 		options: {
 			noIsPseudoSelector: true,
 		},
@@ -130,14 +139,12 @@ postcssTape(plugin)({
 	},
 	'ignore': {
 		message: 'ignores invalid entries',
-		warnings: 1
 	},
 	'ignore:no-is-pseudo-selector': {
 		message: 'ignores invalid entries { noIsPseudoSelector: true }',
 		options: {
 			noIsPseudoSelector: true,
 		},
-		warnings: 1
 	},
 	'mixin-declaration': {
 		message: 'supports other visitors (mixin declaration)',

plugins/postcss-nesting/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changes to PostCSS Nesting
 
+### Unreleased (minor)
+
+- Add support for nested selectors that that begin with a letter
+- Add warning when using the deprecated `@nest` rule
+	- you can silence this warning with a new `silenceAtNestWarning` plugin option
+	- you can migrate your code to the latest syntax with our [Stylelint Plugin](https://github.com/csstools/postcss-plugins/tree/main/plugins-stylelint/no-at-nest-rule#csstoolsstylelint-no-at-nest-rule)
+
 ### 11.2.2 (March 25, 2023)
 
 - Improved: support for mixins

plugins/postcss-nesting/README.md

@@ -77,39 +77,21 @@ instructions for:
 Previous iterations of the [CSS Nesting specification] required using `@nest` for certain selectors.
 
 `@nest` was removed from the specification completely.
-Future versions of this plugin will first warn and then error if you use `@nest`.
+Future versions of this plugin will error if you use `@nest`.
 
-We advice everyone to migrate their codebase **now** to nested CSS without `@nest`.
+We advice everyone to migrate their codebase **now** to nested CSS without `@nest`.  
+We published a [Stylelint Plugin](https://github.com/csstools/postcss-plugins/tree/main/plugins-stylelint/no-at-nest-rule#csstoolsstylelint-no-at-nest-rule) to help you migrate.
 
-## ⚠️ Nested selectors must start with a symbol
+example warning:
+> `@nest` was removed from the CSS Nesting specification and will be removed from PostCSS Nesting in the next major version.
+> Change `@nest foo & {}` to `foo & {}` to migrate to the latest standard.
 
-The current version of the [CSS Nesting specification](https://www.w3.org/TR/2023/WD-css-nesting-1-20230214/#example-34e8e94f) disallows nested selectors to start with a letter (i.e. a tag name or element selector). To write such selectors, they need to be prefixed with `& ` or wrapped with `:is()`.
+You can silence this warning with a new `silenceAtNestWarning` plugin option.
 
-You will get a warning when selectors start with a letter:
-> Nested selectors must start with a symbol and "span" begins with a letter.
-
-```pcss
-.foo {
-	/* ❌ invalid */
-	span {
-		color: hotpink;
-	}
-
-	/* ✅ valid */
-	& span {
-		color: hotpink;
-	}
-
-	/* ❌ invalid */
-	span & {
-		color: hotpink;
-	}
-
-	/* ✅ valid */
-	:is(span) & {
-		color: hotpink;
-	}
-}	
+```js
+postcssNesting({
+	silenceAtNestWarning: true
+})
 ```
 
 ## Options

plugins/postcss-nesting/dist/index.cjs

@@ -3,6 +3,8 @@ import type { PluginCreator } from 'postcss';
 export type pluginOptions = {
     /** Avoid the `:is()` pseudo class as much as possible. default: false */
     noIsPseudoSelector?: boolean;
+    /** Silence the `@nest` warning. */
+    silenceAtNestWarning?: boolean;
 };
 declare const creator: PluginCreator<pluginOptions>;
 export default creator;

plugins/postcss-nesting/dist/index.d.ts

@@ -1,3 +1,2 @@
 import { options } from '../options';
-import type { Node, Result } from 'postcss';
-export default function mergeSelectors(node: Node, postcssResult: Result, fromSelectors: Array<string>, toSelectors: Array<string>, opts: options, fromAtNest?: boolean): any[];
+export default function mergeSelectors(fromSelectors: Array<string>, toSelectors: Array<string>, opts: options): any[];

plugins/postcss-nesting/dist/index.mjs

@@ -1,3 +1,4 @@
 export type options = {
     noIsPseudoSelector: boolean;
+    silenceAtNestWarning: boolean;
 };