[styled-engine] Add enableCssLayer prop to StyledEngineProvider (@siriwatknp) (#45563)

Author: github-actions[bot]

packages/mui-styled-engine/src/StyledEngineProvider/StyledEngineProvider.d.ts

@@ -2,6 +2,7 @@ import * as React from 'react';
 
 export interface StyledEngineProviderProps {
   children?: React.ReactNode;
+  enableCssLayer?: boolean;
   injectFirst?: boolean;
 }
 

packages/mui-styled-engine/src/StyledEngineProvider/StyledEngineProvider.js

@@ -5,6 +5,23 @@ import { CacheProvider } from '@emotion/react';
 import createCache from '@emotion/cache';
 import { StyleSheet } from '@emotion/sheet';
 
+// Need to add a private variable to test the generated CSS from Emotion, this is the simplest way to do it.
+// We can't test the CSS from `style` tag easily because the `speedy: true` (produce empty text content) is enabled by Emotion.
+// Even if we disable it, JSDOM needs extra configuration to be able to parse `@layer` CSS.
+export const TEST_INTERNALS_DO_NOT_USE = {
+  /**
+   * to intercept the generated CSS before inserting to the style tag, so that we can check the generated CSS.
+   *
+   * let rule;
+   * TEST_INTERNALS_DO_NOT_USE.insert = (...args) => {
+   *    rule = args[0];
+   * };
+   *
+   * expect(rule).to.equal(...);
+   */
+  insert: undefined,
+};
+
 // We might be able to remove this when this issue is fixed:
 // https://github.com/emotion-js/emotion/issues/2790
 const createEmotionCache = (options, CustomSheet) => {
@@ -23,11 +40,11 @@ const createEmotionCache = (options, CustomSheet) => {
   return cache;
 };
 
-let cache;
+let insertionPoint;
 if (typeof document === 'object') {
   // Use `insertionPoint` over `prepend`(deprecated) because it can be controlled for GlobalStyles injection order
   // For more information, see https://github.com/mui/material-ui/issues/44597
-  let insertionPoint = document.querySelector('[name="emotion-insertion-point"]');
+  insertionPoint = document.querySelector('[name="emotion-insertion-point"]');
   if (!insertionPoint) {
     insertionPoint = document.createElement('meta');
     insertionPoint.setAttribute('name', 'emotion-insertion-point');
@@ -37,32 +54,67 @@ if (typeof document === 'object') {
       head.prepend(insertionPoint);
     }
   }
-  /**
-   * This is for client-side apps only.
-   * A custom sheet is required to make the GlobalStyles API injected above the insertion point.
-   * This is because the [sheet](https://github.com/emotion-js/emotion/blob/main/packages/react/src/global.js#L94-L99) does not consume the options.
-   */
-  class MyStyleSheet extends StyleSheet {
-    insert(rule, options) {
-      if (this.key && this.key.endsWith('global')) {
-        this.before = insertionPoint;
+}
+
+function getCache(injectFirst, enableCssLayer) {
+  if (injectFirst || enableCssLayer) {
+    /**
+     * This is for client-side apps only.
+     * A custom sheet is required to make the GlobalStyles API injected above the insertion point.
+     * This is because the [sheet](https://github.com/emotion-js/emotion/blob/main/packages/react/src/global.js#L94-L99) does not consume the options.
+     */
+    class MyStyleSheet extends StyleSheet {
+      insert(rule, options) {
+        if (TEST_INTERNALS_DO_NOT_USE.insert) {
+          return TEST_INTERNALS_DO_NOT_USE.insert(rule, options);
+        }
+        if (this.key && this.key.endsWith('global')) {
+          this.before = insertionPoint;
+        }
+        return super.insert(rule, options);
       }
-      return super.insert(rule, options);
     }
+    const emotionCache = createEmotionCache(
+      {
+        key: 'css',
+        insertionPoint: injectFirst ? insertionPoint : undefined,
+      },
+      MyStyleSheet,
+    );
+    if (enableCssLayer) {
+      const prevInsert = emotionCache.insert;
+      emotionCache.insert = (...args) => {
+        if (!args[1].styles.startsWith('@layer')) {
+          // avoid nested @layer
+          args[1].styles = `@layer mui {${args[1].styles}}`;
+        }
+        return prevInsert(...args);
+      };
+    }
+    return emotionCache;
   }
-  cache = createEmotionCache({ key: 'css', insertionPoint }, MyStyleSheet);
+  return undefined;
 }
 
 export default function StyledEngineProvider(props) {
-  const { injectFirst, children } = props;
-  return injectFirst && cache ? <CacheProvider value={cache}>{children}</CacheProvider> : children;
+  const { injectFirst, enableCssLayer, children } = props;
+  const cache = React.useMemo(
+    () => getCache(injectFirst, enableCssLayer),
+    [injectFirst, enableCssLayer],
+  );
+  return cache ? <CacheProvider value={cache}>{children}</CacheProvider> : children;
 }
 
 StyledEngineProvider.propTypes = {
   /**
    * Your component tree.
    */
   children: PropTypes.node,
+  /**
+   * If `true`, the styles are wrapped in `@layer mui`.
+   * Learn more about [Cascade layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers).
+   */
+  enableCssLayer: PropTypes.bool,
   /**
    * By default, the styles are injected last in the <head> element of the page.
    * As a result, they gain more specificity than any other style sheet.

packages/mui-styled-engine/src/StyledEngineProvider/StyledEngineProvider.test.js

@@ -0,0 +1,52 @@
+import * as React from 'react';
+import { StyledEngineProvider, GlobalStyles } from '@mui/styled-engine';
+import { createRenderer } from '@mui/internal-test-utils';
+import { expect } from 'chai';
+import { TEST_INTERNALS_DO_NOT_USE } from './StyledEngineProvider';
+
+describe('[Emotion] StyledEngineProvider', () => {
+  const { render } = createRenderer();
+
+  let rule;
+
+  before(() => {
+    TEST_INTERNALS_DO_NOT_USE.insert = (...args) => {
+      rule = args[0];
+    };
+  });
+
+  after(() => {
+    delete TEST_INTERNALS_DO_NOT_USE.insert;
+  });
+
+  beforeEach(() => {
+    rule = undefined;
+  });
+
+  it('should create styles with @layer', () => {
+    render(
+      <StyledEngineProvider enableCssLayer>
+        <GlobalStyles styles={{ html: { color: 'red' } }} />
+      </StyledEngineProvider>,
+    );
+    expect(rule).to.equal('@layer mui{html{color:red;}}');
+  });
+
+  it('should do nothing if the styles already in a layer', () => {
+    render(
+      <StyledEngineProvider enableCssLayer>
+        <GlobalStyles styles={{ '@layer components': { html: { color: 'red' } } }} />
+      </StyledEngineProvider>,
+    );
+    expect(rule).to.equal('@layer components{html{color:red;}}');
+  });
+
+  it('able to config layer order through GlobalStyles', () => {
+    render(
+      <StyledEngineProvider enableCssLayer>
+        <GlobalStyles styles="@layer theme, base, mui, components, utilities;" />
+      </StyledEngineProvider>,
+    );
+    expect(rule).to.equal('@layer theme,base,mui,components,utilities;');
+  });
+});