Feature/stylelint rules (#360)

.changeset/mean-pens-juggle.md

@@ -0,0 +1,6 @@
+---
+"@10up/stylelint-config": major
+---
+
+Discourage usage of `@nest` by disallowing the at-rule.
+Adding support for new way of doing nesting as per latest Nesting Spec (as implemented by browsers in 2023).

packages/stylelint-config/index.js

@@ -2,6 +2,7 @@ module.exports = {
 	extends: ['stylelint-config-recommended'],
 	plugins: ['stylelint-stylistic', 'stylelint-declaration-strict-value', 'stylelint-order'],
 	rules: {
+		'at-rule-disallowed-list': ['nest'],
 		'at-rule-empty-line-before': [
 			'always',
 			{
@@ -77,7 +78,7 @@ module.exports = {
 					'Selector should use lowercase and separate words with hyphens (selector-id-pattern)',
 			},
 		],
-		'selector-nested-pattern': ['^&'],
+		'selector-nested-pattern': '^&|\\s&$',
 		'selector-pseudo-element-colon-notation': 'double',
 		'selector-type-case': 'lower',
 		'stylistic/at-rule-name-case': 'lower',

packages/toolkit/UPGRADING.md

@@ -5,11 +5,11 @@
 There are a few major changes in this release. While it probably won't break your build, it's worth noting everything that's changed.
 
 ### Node version
-Minimum Node version is now 18
+Minimum Node version is now 18 to follow [Node LTS](https://nodejs.org/en/about/previous-releases).
 
 ### useBlockAssets on by default.
 
-useBlockAssets is now true by default. If you are not ready for it yet. Set useBlockAssets to false in your 10up-toolkit package.json config.
+`useBlockAssets` is now `true` by default. If you are not ready for it yet. Set `useBlockAssets` to `false` in your 10up-toolkit package.json config.
 
 ```json
 {
@@ -21,22 +21,30 @@ useBlockAssets is now true by default. If you are not ready for it yet. Set useB
 ```
 
 ### Stylelint
-Stylelint has been updated to 15. When upgrading toolkit ensure you also update `@10up/stylelint-config` to 3, in case you are specifying it in your package.json. If you're not npm should resolve the peer dependency automatically.
+Stylelint has been updated to 15. When upgrading toolkit ensure you also update `@10up/stylelint-config` to 3, in case you are specifying it in your package.json. If you're not, npm should resolve the peer dependency automatically.
+
+Please note that we have updated the Stylelint Rules to account for the new version of PostCSS Nesting which, according to the spec, no longer supports `@nest`. If you are using `@nest` in your CSS, you will need to update your code to use `@at-root` instead. You can read more about this change in the [Upcoming changes to CSS Nesting](https://preset-env.cssdb.org/blog/upcoming-changes-css-nesting/).
 
 ### PostCSS
 Swapping `postcss-editor-styles` with `postcss-editor-styles-wrapper` which is compatible with PostCSS 8. This should be a seamless change as this is a fork of the original package that was updated to be compatible with PostCSS 8 and fixes wrong behaviour in some circumstances.
 
 For those referencing `postcss-editor-styles` in `postcss.config.js` should update the plugin name to `postcss-editor-styles-wrapper`.
 
-`postcss-preset-env` has been updated to `^9.0.0` from `^7.0.0`. This is a major version bump and there are some breaking changes. See the [postcss-preset-env changelog](https://github.com/csstools/postcss-plugins/wiki/PostCSS-Preset-Env-8) for version 8 if you run into issues. It's hard to know every single build that could be affected by this change, but here is the only one we think it's worth flagging in this document:
-  * PostCSS Custom Media Breaking Change. If you used media queries without parentheses, you'll need to add them. See [PostCSS Custom Media Breaking Change](https://github.com/csstools/postcss-plugins/wiki/PostCSS-Preset-Env-8#postcss-custom-media-breaking-changes)
-
-```diff
-@custom-media --foo (min-width: 320px);
-
-- @media --foo {}
-+ @media (--foo) {}
-```
+`postcss-preset-env` has been updated to `^9.0.0` from `^7.0.0`. This is a major version bump and there are some breaking changes. It's hard to know every single build that could be affected by this change, so here is a quick list of the things that could be breaking:
+
+* If you were relying on any of the following plugins, you will need to set the option `enableClientSidePolyfills` to true now. Also, those plugins themselves are breaking.
+	* `:blank pseudo-class` polyfill.
+	* `:focus-visible pseudo-class` polyfill.
+	* `:focus-within pseudo-class` polyfill.
+	* `:has pseudo-class` polyfill.
+	* `@media (prefers-color-scheme)` polyfill.
+* If you were relying on `importFrom` and/or `exportTo` you're in trouble since those options have been removed. There's a new plugin that could help with `importFrom` especially if any Modular CSS was the reason. See [PostCSS Global Data](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-global-data#readme). We’re also considering bundling this plugin into toolkit eventually, if you’re interested please chime in on [the issue](https://github.com/10up/10up-toolkit/issues/340)!
+* If you were relying on `postcss-env-function`, you will need to add the plugin manually. The plugin has been deprecated and removed from [PostCSS Preset Env](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme).
+* If you were using complex logic in custom media queries, you might want to revisit the output is still the same. Also, if you were using custom media queries without parenthesis, you will need to add them.
+* If you were leveraging `::before` or `::after` in custom selectors, you will need to rewrite your custom selectors to remove these. Similarly, if you use complex selectors (e.g. `.foo + .bar`) you will need to verify your project. The matched elements can be different.
+* If you were relying on the `:dir` generated by [PostCSS Logical](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-logical#readme) to handle `margin-inline` and such, then you need to refactor your code.
+
+See the [postcss-preset-env changelog](https://github.com/csstools/postcss-plugins/wiki/PostCSS-Preset-Env-8) for version 8 if you run into issues related to this change.
 
 ### Eslint
 The rule `jsdoc/newline-after-description` has been removed in the latest `eslint-plugin-jsdoc` and thus has been removed in the latest version of toolkit. If you have this rule in your own eslint config file you will need to remove it.