Improve @at-root behavior

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>