Improve @at-root behavior (#147)

* tests: Normalize expected and actual strings to reduce noise

* style: Add @ts-check and JSDoc type definitions to surface errors

* tests: Add more passing tests

* tests: Add failing tests for valid uses of `@at-root`

* style: Rename functions and variables for clarity

* rafactor: Resolve non-critical/false-positive type-checking issues

* fix: Logic/typing error when handling @at-root rules

* refactor: Simplify existing logic

* fix: Move all preceeding comments with rule

* fix: `@layer` blocks should also bubble

* fix: Correctly handle `with`/`without` parameters on `@at-root`

* feat: Add option `rootRuleName` to rename the custom `@at-root` rule

* style: Auto formatting/linting

* fix: Remove hasRootRule optimization

* fix: Add back hasRootRule optimization, scoped to root node

As per examples given in the postcss docs:
https://github.com/postcss/postcss/blob/main/docs/writing-a-plugin.md#step-4-change-nodes

* docs: Update README

* style: Reformat test input

* tests: Add more `@at-rule` test, some failing

* fix: Failing `@at-root` edge cases

* style: Fix typo in function name, remove console.log

* refactor: Remove @ts-check hack code path, use type assertion instead

* test: Remove comments

* refactor: Use root#walkAtRules

* chore: Tweak eslint rule value

* refactor: Fix linting errors …

Not sure how/why this didn't show up yesterday or the day before.
VSCode's ESLint plugin must have silently crashed or something.

CHANGELOG.md

@@ -1,6 +1,14 @@
 # Change Log
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Upcoming...
+* ... <!-- Add new lines here. -->
+* fix: Correctly handle `with`/`without` parameters on `@at-root`
+* feat: Add option `rootRuleName` to rename the custom `@at-root` rule
+* fix: Errors when handling sibling `@at-root` rule blocks
+* fix: Move all preceeding comments with rule
+* fix: `@layer` blocks should also bubble
+
 ## 5.0.6
 * Fixed custom at-rules nesting (by @bsak-shell).
 

README.md

@@ -119,8 +119,8 @@ module.exports = {
 
 ### `bubble`
 
-By default, plugin will bubble only `@media` and `@supports` at-rules.
-You can add your custom at-rules to this list by `bubble` option:
+By default, plugin will bubble only `@media`, `@supports` and `@layer`
+at-rules. Use this option to add your custom at-rules to this list.
 
 ```js
 postcss([ require('postcss-nested')({ bubble: ['phone'] }) ])
@@ -196,3 +196,27 @@ Will be compiled to:
 ```
 
 This is especially useful if you want to export the empty classes with `postcss-modules`.
+
+
+### `rootRuleName`
+
+The plugin supports the SCSS custom at-rule `@at-root` which breaks rule
+blocks out of their nested position. If you want, you can choose a new
+custom name for this rule in your code.
+
+```js
+postcss([ require('postcss-nested')({ rootRuleName: '_escape-nesting' }) ])
+```
+
+```css
+/* input */
+.a {
+  color: white;
+  @_escape-nesting {
+    .b { color: black; }
+  }
+}
+/* output */
+.a { color: white; }
+.b { color: black; }
+```

index.d.ts

@@ -6,8 +6,8 @@ import { PluginCreator } from 'postcss'
 declare namespace nested {
   interface Options {
     /**
-     * By default, plugin will bubble only `@media` and `@supports` at-rules.
-     * You can add your custom at-rules to this list by this option.
+     * By default, plugin will bubble only `@media`, `@supports` and `@layer`
+     * at-rules. Use this option to add your custom at-rules to this list.
      */
     bubble?: string[]
 
@@ -24,6 +24,13 @@ declare namespace nested {
      * to preserve them.
      */
     preserveEmpty?: boolean
+
+    /**
+     * The plugin supports the SCSS custom at-rule `@at-root` which breaks
+     * rule blocks out of their nested position. If you want, you can choose
+     * a new custom name for this rule in your code.
+     */
+    rootRuleName?: string
   }
 
   type Nested = PluginCreator<Options>