Transform global selectors (#119)

* Replace :root, body, html with the prefix

* Add details about global selectors

* Add option to not transform global selectors

* Merge redundant descriptions

Author: RadValentin

README.md

@@ -27,35 +27,32 @@ $ npm install postcss-prefix-selector
 
 ## Usage with PostCSS
 
+A prefix is added before most selectors. Below is an example of how CSS will be transformed by adding a prefix called `.namespace`.
+
 ```js
 const prefixer = require('postcss-prefix-selector')
 
 // css to be processed
 const css = fs.readFileSync("input.css", "utf8")
 
 const out = postcss().use(prefixer({
-  prefix: '.some-selector',
+  prefix: '.namespace',
   exclude: ['.c'],
-
-  // Optional transform callback for case-by-case overrides
-  transform: function (prefix, selector, prefixedSelector, filePath, rule) {
-    if (selector === 'body') {
-      return 'body' + prefix;
-    } else {
-      return prefixedSelector;
-    }
-  }
 })).process(css).css
 ```
 
-Using the options above and the CSS below...
-
 ```css
-body {
-  background: red;
+/* Input */
+.a, .b {
+  color: aqua;
 }
 
-.a, .b {
+.c {
+  color: coral;
+}
+
+/* Output */
+.namespace .a, .namespace .b {
   color: aqua;
 }
 
@@ -64,19 +61,45 @@ body {
 }
 ```
 
-You will get the following output
+Please note that global selectors (`html`, `body`, `:root`) cannot be prefixed so instead they will be replaced with the prefix. This behaviour can be disabled with the `skipGlobalSelectors` option.
 
 ```css
-body.some-selector {
-  background: red;
-}
+/* Input */
+:root { --bs-blue:#0d6efd; }
+html { padding: 0; }
+body { margin: 0; }
+
+/* Output */
+.namespace { --bs-blue:#0d6efd; }
+.namespace { padding: 0; }
+.namespace { margin: 0; }
+```
 
-.some-selector .a, .some-selector .b {
-  color: aqua;
+It's also possible to customize the way prefixing is done by defining a transform function:
+
+```js
+const out = postcss().use(prefixer({
+  prefix: '.namespace',
+  // Optional transform callback for case-by-case overrides
+  transform: function (prefix, selector, prefixedSelector, filePath, rule) {
+    if (selector === 'body') {
+      return 'body' + prefix;
+    } else {
+      return prefixedSelector;
+    }
+  }
+})).process(css).css
+```
+
+```css
+/* Input */
+body {
+  background: red;
 }
 
-.c {
-  color: coral;
+/* Output */
+body.namespace {
+  background: red;
 }
 ```
 
@@ -180,6 +203,7 @@ export default defineConfig({
 | `transform` | `Function` | In cases where you may want to use the prefix differently for different selectors, it is possible to pass in a custom transform method |
 | `ignoreFiles` | `string[]` or `RegExp[]` | List of ignored files for processing |
 | `includeFiles` | `string[]` or `RegExp[]` | List of included files for processing |
+| `skipGlobalSelectors` | `boolean` |  When enabled, global selectors (`html`, `body`, `root`) won't be modified by the prefixer. Default: `false`. | 
 
 ## Maintainer
 
@@ -193,7 +217,7 @@ This project uses Mocha. If you submit a PR, please add appropriate tests and ma
 
 ## License
 
-[MIT](LICENSE) © 2015-2022 Jonathan Ong.
+[MIT](LICENSE) © 2015-2024 Jonathan Ong.
 
 [gitpod-image]: https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod
 [gitpod-url]: https://gitpod.io/#https://github.com/RadValentin/postcss-prefix-selector

index.js

@@ -48,6 +48,15 @@ const prefixPlugin = (options = {}) => {
               );
             }
 
+            // replace :root, body, html with the prefix
+            if ([':root', 'body', 'html'].some(globalSel => selector.startsWith(globalSel))) {
+              if (options.skipGlobalSelectors) {
+                return selector;
+              }
+
+              return selector.replace(/(html\s+body|:root\s+body|html|:root|body)/gm, prefix);
+            }
+
             return prefixWithSpace + selector;
           });
         }

test/fixtures/global-selectors.css

@@ -0,0 +1,19 @@
+html {
+  margin: 0;
+}
+
+body {
+  padding: 0;
+}
+
+html body div {
+  color: blue;
+}
+
+:root {
+  --bs-blue:#0d6efd;
+}
+
+:root .a {
+  --bs-green: #bada55;
+}

test/fixtures/global-selectors.expected.css

@@ -0,0 +1,19 @@
+.prefix {
+  margin: 0;
+}
+
+.prefix {
+  padding: 0;
+}
+
+.prefix div {
+  color: blue;
+}
+
+.prefix {
+  --bs-blue:#0d6efd;
+}
+
+.prefix .a {
+  --bs-green: #bada55;
+}

test/fixtures/pseudo-classes.css

@@ -0,0 +1,31 @@
+:first-child {
+  color: pink;
+}
+
+:hover {
+  color: blue;
+}
+
+:active {
+  color: red;
+}
+
+* {
+  background-color: red;
+}
+
+::first-letter {
+  color: pink;
+}
+
+::before {
+  content: '';
+  width: 10px;
+  height: 10px;
+  background-color: blue;
+  position: absolute;
+}
+
+#wow {
+  color: yellow;
+}

test/fixtures/pseudo-classes.expected.css

@@ -0,0 +1,31 @@
+.prefix :first-child {
+  color: pink;
+}
+
+.prefix :hover {
+  color: blue;
+}
+
+.prefix :active {
+  color: red;
+}
+
+.prefix * {
+  background-color: red;
+}
+
+.prefix ::first-letter {
+  color: pink;
+}
+
+.prefix ::before {
+  content: '';
+  width: 10px;
+  height: 10px;
+  background-color: blue;
+  position: absolute;
+}
+
+.prefix #wow {
+  color: yellow;
+}

test/test.js

@@ -348,6 +348,35 @@ it('should prefix postcss nested selectors', () => {
   assert.equal(out, expected);
 });
 
+it('should prefix pseudo-classes', () => {
+  const out = postcss()
+  .use(prefixer({ prefix: '.prefix' }))
+  .process(getFixtureContents('pseudo-classes.css')).css;
+
+  const expected = getFixtureContents('pseudo-classes.expected.css');
+  assert.equal(out, expected);
+});
+
+it('should replace :root, body and html with the prefix', () => {
+  const out = postcss()
+  .use(prefixer({ prefix: '.prefix' }))
+  .process(getFixtureContents('global-selectors.css')).css;
+
+  const expected = getFixtureContents('global-selectors.expected.css');
+  assert.equal(out, expected);
+});
+
+it('should skip global selectors when option is enabled', () => {
+  const out = postcss()
+  .use(prefixer({ 
+    prefix: '.prefix',
+    skipGlobalSelectors: true
+  })).process(getFixtureContents('global-selectors.css')).css;
+
+  const expected = getFixtureContents('global-selectors.css');
+  assert.equal(out, expected);
+});
+
 function getFixtureContents(name) {
   return fs.readFileSync(`test/fixtures/${name}`, 'utf8').trim();
 }