emotion-js · thomaslindstrom · Jul 12, 2024 · Jul 12, 2024 · Jul 12, 2024 · Jul 12, 2024
diff --git a/.changeset/brown-points-push.md b/.changeset/brown-points-push.md
@@ -0,0 +1,5 @@
+---
+'@emotion/cache': minor
+---
+
+Add option `explicitAmpersand` to opt-out of automatically prefixing pseudo classes with the parent class
diff --git a/packages/cache/README.md b/packages/cache/README.md
@@ -60,3 +60,37 @@ A DOM node that emotion will insert all of its style tags into. This is useful f
 `boolean`
 
 A boolean representing whether to prepend rather than append style tags into the specified container DOM node.
+
+### `explicitAmpersand`
+
+`boolean`
+
+Defaults to `false`. Opt-out of automatic pseudo class prefixing.
+
+Consider the following component:
+
+```jsx
+<article
+  css={css`
+    :where([data-theme='dark']) & {
+      /* ... */
+    }
+  `}
+/>
+```
+
+With `explicitAmpersand` set to `true`:
+
+```css
+:where([data-theme='dark']) .emotion-article {
+  /* ... */
+}
+```
+
+With `explicitAmpersand` set to `false`:
+
+```css
+.emotion-article:where([data-theme='dark']) .emotion-article {
+  /* ... */
+}
+```
diff --git a/packages/cache/__tests__/__snapshots__/index.js.snap b/packages/cache/__tests__/__snapshots__/index.js.snap
@@ -57,4 +57,112 @@ exports[`should accept insertionPoint option 1`] = `
 </head>
 `;
 
+exports[`should not prefix pseudo-classes automatically when using explicitAmpersand option 1`] = `
+:where([dir='rtl']) .emotion-0 {
+  color: red;
+}
+
+.emotion-0 :is(p, ul)+:is(p, ul) {
+  margin-top: 1em;
+}
+
+.emotion-0:before {
+  content: 'test';
+}
+
+<body>
+  <div
+    id="container"
+  >
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0{}
+    </style>
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      :where([dir='rtl']) .emotion-0{color:red;}
+    </style>
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0 :is(p, ul)+:is(p, ul){margin-top:1em;}
+    </style>
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0:before{content:'test';}
+    </style>
+  </div>
+  <div>
+    <div
+      class="emotion-0"
+    />
+  </div>
+</body>
+`;
+
+exports[`should prefix pseudo-classes automatically when not using explicitAmpersand option 1`] = `
+.emotion-0:where([dir='rtl']) .emotion-0 {
+  color: red;
+}
+
+.emotion-0:is(p, ul)+:is(p, ul) {
+  margin-top: 1em;
+}
+
+.emotion-0:before {
+  content: 'test';
+}
+
+<body>
+  <div
+    id="container"
+  >
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0{}
+    </style>
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0:where([dir='rtl']) .emotion-0{color:red;}
+    </style>
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0:is(p, ul)+:is(p, ul){margin-top:1em;}
+    </style>
+    <style
+      data-emotion="test-container"
+      data-s=""
+    >
+
+      .emotion-0:before{content:'test';}
+    </style>
+  </div>
+  <div>
+    <div
+      class="emotion-0"
+    />
+  </div>
+</body>
+`;
+
 exports[`throws correct error with invalid key 1`] = `"Emotion key must only contain lower case alphabetical characters and - but "." was passed"`;
diff --git a/packages/cache/__tests__/index.js b/packages/cache/__tests__/index.js
@@ -2,7 +2,7 @@
 import 'test-utils/next-env'
 import { safeQuerySelector } from 'test-utils'
 import createCache from '@emotion/cache'
-import { jsx, CacheProvider } from '@emotion/react'
+import { jsx, CacheProvider, css } from '@emotion/react'
 import { render } from '@testing-library/react'
 
 test('throws correct error with invalid key', () => {
@@ -54,3 +54,68 @@ it('should accept container option', () => {
 
   expect(document.body).toMatchSnapshot()
 })
+
+it('should not prefix pseudo-classes automatically when using explicitAmpersand option', () => {
+  const body = safeQuerySelector('body')
+  body.innerHTML = `<div id="container" />`
+
+  const cache = createCache({
+    key: 'test-container',
+    container: safeQuerySelector('#container'),
+    explicitAmpersand: true
+  })
+
+  render(
+    <CacheProvider value={cache}>
+      <div
+        css={css`
+          :where([dir='rtl']) & {
+            color: red;
+          }
+
+          :is(p, ul) + :is(p, ul) {
+            margin-top: 1em;
+          }
+
+          &:before {
+            content: 'test';
+          }
+        `}
+      />
+    </CacheProvider>
+  )
+
+  expect(document.body).toMatchSnapshot()
+})
+
+it('should prefix pseudo-classes automatically when not using explicitAmpersand option', () => {
+  const body = safeQuerySelector('body')
+  body.innerHTML = `<div id="container" />`
+
+  const cache = createCache({
+    key: 'test-container',
+    container: safeQuerySelector('#container')
+  })
+
+  render(
+    <CacheProvider value={cache}>
+      <div
+        css={css`
+          :where([dir='rtl']) & {
+            color: red;
+          }
+
+          :is(p, ul) + :is(p, ul) {
+            margin-top: 1em;
+          }
+
+          &:before {
+            content: 'test';
+          }
+        `}
+      />
+    </CacheProvider>
+  )
+
+  expect(document.body).toMatchSnapshot()
+})
diff --git a/packages/cache/src/index.js b/packages/cache/src/index.js
@@ -29,6 +29,7 @@ export type Options = {
   container?: HTMLElement,
   speedy?: boolean,
   prepend?: boolean,
+  explicitAmpersand?: boolean,
   insertionPoint?: HTMLElement
 }
 */
@@ -115,7 +116,9 @@ let createCache = (options /*: Options */) /*: EmotionCache */ => {
     sheet: StyleSheet,
     shouldCache: boolean
   ) => string | void */
-  const omnipresentPlugins = [compat, removeLabel]
+  const omnipresentPlugins = options.explicitAmpersand
+    ? [removeLabel]
+    : [compat, removeLabel]
 
   if (process.env.NODE_ENV !== 'production') {
     omnipresentPlugins.push(