[styled-engine] Add GlobalStyles component (#24176)

docs/pages/api-docs/css-baseline.json

@@ -1,10 +1,10 @@
 {
-  "props": { "children": { "type": { "name": "node" }, "default": "null" } },
+  "props": { "children": { "type": { "name": "node" } } },
   "name": "CssBaseline",
-  "styles": { "classes": [], "globalClasses": {}, "name": "MuiCssBaseline" },
-  "spread": false,
+  "styles": { "classes": [], "globalClasses": {}, "name": null },
+  "spread": true,
   "filename": "/packages/material-ui/src/CssBaseline/CssBaseline.js",
   "inheritance": null,
   "demos": "<ul><li><a href=\"/components/css-baseline/\">Css Baseline</a></li></ul>",
-  "styledComponent": false
+  "styledComponent": true
 }

docs/src/pages/customization/how-to-customize/GlobalCssOverride.js

@@ -1,21 +1,11 @@
 import * as React from 'react';
-import { withStyles } from '@material-ui/core/styles';
-import Button from '@material-ui/core/Button';
-
-const GlobalCss = withStyles({
-  // @global is handled by jss-plugin-global.
-  '@global': {
-    '.MuiButton-root': {
-      fontSize: '1rem',
-    },
-  },
-})(() => null);
+import GlobalStyles from '@material-ui/core/GlobalStyles';
 
 export default function GlobalCssOverride() {
   return (
     <React.Fragment>
-      <GlobalCss />
-      <Button>font-size: 1rem</Button>
+      <GlobalStyles styles={{ h1: { color: 'grey' } }} />
+      <h1>Grey h1 element</h1>
     </React.Fragment>
   );
 }

docs/src/pages/customization/how-to-customize/GlobalCssOverride.tsx

@@ -1,21 +1,11 @@
 import * as React from 'react';
-import { withStyles } from '@material-ui/core/styles';
-import Button from '@material-ui/core/Button';
-
-const GlobalCss = withStyles({
-  // @global is handled by jss-plugin-global.
-  '@global': {
-    '.MuiButton-root': {
-      fontSize: '1rem',
-    },
-  },
-})(() => null);
+import GlobalStyles from '@material-ui/core/GlobalStyles';
 
 export default function GlobalCssOverride() {
   return (
     <React.Fragment>
-      <GlobalCss />
-      <Button>font-size: 1rem</Button>
+      <GlobalStyles styles={{ h1: { color: 'grey' } }} />
+      <h1>Grey h1 element</h1>
     </React.Fragment>
   );
 }

docs/src/pages/customization/how-to-customize/OverrideCssBaseline.js

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import CssBaseline from '@material-ui/core/CssBaseline';
+import { ThemeProvider, createMuiTheme } from '@material-ui/core/styles';
+
+const theme = createMuiTheme({
+  components: {
+    MuiCssBaseline: {
+      styleOverrides: {
+        h1: {
+          color: 'grey',
+        },
+      },
+    },
+  },
+});
+
+export default function OverrideCssBaseline() {
+  return (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      <h1>Grey h1 element</h1>
+    </ThemeProvider>
+  );
+}

docs/src/pages/customization/how-to-customize/OverrideCssBaseline.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import CssBaseline from '@material-ui/core/CssBaseline';
+import { ThemeProvider, createMuiTheme } from '@material-ui/core/styles';
+
+const theme = createMuiTheme({
+  components: {
+    MuiCssBaseline: {
+      styleOverrides: {
+        h1: {
+          color: 'grey',
+        },
+      },
+    },
+  },
+});
+
+export default function OverrideCssBaseline() {
+  return (
+    <ThemeProvider theme={theme}>
+      <CssBaseline />
+      <h1>Grey h1 element</h1>
+    </ThemeProvider>
+  );
+}

docs/src/pages/customization/how-to-customize/how-to-customize.md

@@ -1,4 +1,4 @@
-# Customizing components
+# How to customize
 
 <p class="description">You can easily customize the appearance of a Material-UI component.</p>
 
@@ -165,45 +165,18 @@ Please take a look at the theme's [global overrides page](/customization/theme-c
 
 Components expose [global class names](/styles/advanced/#with-material-ui-core) to enable customization with CSS.
 
-```jsx
-const GlobalCss = withStyles({
-  // @global is handled by jss-plugin-global.
-  '@global': {
-    '.MuiButton-root': {
-      fontSize: '1rem',
-    },
-  },
-})(() => null);
-
-// …
-
-<GlobalCss />;
+```css
+.MuiButton-root {
+  fontsize: '1rem';
+}
 ```
 
-If you are using the [CssBaseline](/components/css-baseline/) component to apply global resets, it can also be used to apply global styles. For instance:
+You can reference the [Styles library interoperability guide](/guides/interoperability/) to find examples of this using different styles libraries or plain CSS.
 
-```jsx
-const theme = createMuiTheme({
-  components: {
-    MuiCssBaseline: {
-      styleOverrides: {
-        '@global': {
-          html: {
-            WebkitFontSmoothing: 'auto',
-          },
-        },
-      },
-    },
-  },
-});
-
-// ...
-return (
-  <ThemeProvider theme={theme}>
-    <CssBaseline />
-    {children}
-  </ThemeProvider>
-);
-```
+If you just want to add some global baseline styles for some of the HTML elements, you can use the `GlobalStyles` component. Here is an example of how you can override styles for the `h1` elements.
 
 {{"demo": "pages/customization/how-to-customize/GlobalCssOverride.js", "iframe": true, "height": 100}}
+
+If you are already using the [CssBaseline](/components/css-baseline/) component for setting baseline styles, you can also add these global styles as overrides for this component. Here is how you can achieve the same by using this approach.
+
+{{"demo": "pages/customization/how-to-customize/OverrideCssBaseline.js", "iframe": true, "height": 100}}

docs/src/pages/customization/typography/typography.md

@@ -64,9 +64,7 @@ const theme = createMuiTheme({
   components: {
     MuiCssBaseline: {
       styleOverrides: {
-        '@global': {
-          '@font-face': [raleway],
-        },
+        '@font-face': [raleway],
       },
     },
   },

docs/src/pages/getting-started/faq/faq.md

@@ -95,12 +95,9 @@ const theme = createMuiTheme({
     // Name of the component ⚛️
     MuiCssBaseline: {
       styleOverrides: {
-        // Name of the rule
-        '@global': {
-          '*, *::before, *::after': {
-            transition: 'none !important',
-            animation: 'none !important',
-          },
+        '*, *::before, *::after': {
+          transition: 'none !important',
+          animation: 'none !important',
         },
       },
     },

docs/src/pages/guides/migration-v4/migration-v4.md

@@ -491,6 +491,24 @@ As the core components use emotion as a styled engine, the props used by emotion
 
 ### CssBaseline
 
+- The component was migrated to use the `@material-ui/styled-engine` (`emotion` or `styled-components`) instead of `jss`. You should remove the `@global` key when defining the style overrides for it.
+
+  ```diff
+  const theme = createMuiTheme({
+    components: {
+      MuiCssBaseline: {
+        styleOverrides: {
+  -       '@global': {
+            html: {
+              WebkitFontSmoothing: 'auto',
+            },
+  -       },
+        },
+      },
+    },
+  });
+  ```
+
 - The `body` font size has changed from `theme.typography.body2` (`0.875rem`) to `theme.typography.body1` (`1rem`).
   To return to the previous size, you can override it in the theme:
 

packages/material-ui-styled-engine-sc/src/GlobalStyles/GlobalStyles.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { CSSObject, InterpolationFunction } from 'styled-components';
+
+export interface GlobalStylesProps {
+  defaultTheme?: object;
+  styles: string | CSSObject | InterpolationFunction<any>;
+}
+
+export default function Global(props: GlobalStylesProps): React.ReactElement;

packages/material-ui-styled-engine-sc/src/GlobalStyles/GlobalStyles.js

@@ -0,0 +1,23 @@
+import PropTypes from 'prop-types';
+import { createGlobalStyle } from 'styled-components';
+
+function isEmpty(obj) {
+  return Object.keys(obj).length === 0;
+}
+
+const GlobalStyles = createGlobalStyle((props) => {
+  const { styles, defaultTheme } = props;
+
+  if (typeof styles === 'function') {
+    return styles(isEmpty(props.theme) ? defaultTheme : props.theme);
+  }
+
+  return styles;
+});
+
+export default GlobalStyles;
+
+GlobalStyles.propTypes = {
+  defaultTheme: PropTypes.object,
+  styles: PropTypes.oneOfType([PropTypes.string, PropTypes.object, PropTypes.func]),
+};

packages/material-ui-styled-engine-sc/src/GlobalStyles/GlobalStyles.test.js

@@ -0,0 +1,93 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { createClientRender } from 'test/utils';
+import { ThemeProvider } from 'styled-components';
+import styled from '..';
+import GlobalStyles from './GlobalStyles';
+
+describe('GlobalStyles', () => {
+  const render = createClientRender();
+
+  it('should add global styles', function test() {
+    if (/jsdom/.test(window.navigator.userAgent)) this.skip();
+
+    const { container } = render(
+      <div>
+        <GlobalStyles styles={`span { color: rgb(0, 0, 255); }`} />
+        <span>Blue text</span>
+      </div>,
+    );
+
+    expect(container.getElementsByTagName('span')[0]).toHaveComputedStyle({
+      color: 'rgb(0, 0, 255)',
+    });
+  });
+
+  it('should add global styles using JS syntax', function test() {
+    if (/jsdom/.test(window.navigator.userAgent)) this.skip();
+
+    const { container } = render(
+      <div>
+        <GlobalStyles styles={{ span: { color: 'rgb(0, 0, 255)' } }} />
+        <span>Blue text</span>
+      </div>,
+    );
+
+    expect(container.getElementsByTagName('span')[0]).toHaveComputedStyle({
+      color: 'rgb(0, 0, 255)',
+    });
+  });
+
+  it('should add global styles using function', function test() {
+    if (/jsdom/.test(window.navigator.userAgent)) this.skip();
+
+    const { container } = render(
+      <ThemeProvider theme={{ color: 'rgb(0, 0, 255)' }}>
+        <GlobalStyles styles={(theme) => ({ span: { color: theme.color } })} />
+        <span>Blue text</span>
+      </ThemeProvider>,
+    );
+
+    expect(container.getElementsByTagName('span')[0]).toHaveComputedStyle({
+      color: 'rgb(0, 0, 255)',
+    });
+  });
+
+  it('should give presedence to styled()', function test() {
+    if (/jsdom/.test(window.navigator.userAgent)) this.skip();
+
+    const Span = styled('span')`
+      color: rgb(255, 0, 0);
+    `;
+
+    const { container } = render(
+      <div>
+        <GlobalStyles styles={`span { color: rgb(0, 0, 255); }`} />
+        <Span>Red text</Span>
+      </div>,
+    );
+
+    expect(container.getElementsByTagName('span')[0]).toHaveComputedStyle({
+      color: 'rgb(255, 0, 0)',
+    });
+  });
+
+  it('should give presedence to styled() using JS syntax', function test() {
+    if (/jsdom/.test(window.navigator.userAgent)) this.skip();
+
+    const Span = styled('span')({
+      color: 'rgb(255, 0, 0)',
+    });
+
+    const { container } = render(
+      <div>
+        <GlobalStyles styles={{ span: { color: 'rgb(0, 0, 255)' } }} />
+        <Span>Red text</Span>
+      </div>,
+    );
+
+    expect(container.getElementsByTagName('span')[0]).toHaveComputedStyle({
+      color: 'rgb(255, 0, 0)',
+    });
+  });
+});

packages/material-ui-styled-engine-sc/src/GlobalStyles/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './GlobalStyles';
+export * from './GlobalStyles';

packages/material-ui-styled-engine-sc/src/GlobalStyles/index.js

@@ -0,0 +1 @@
+export { default } from './GlobalStyles';

packages/material-ui-styled-engine-sc/src/index.d.ts

@@ -1,3 +1,6 @@
 export * from 'styled-components';
 export { default } from 'styled-components';
 export { default as StylesProvider } from './StylesProvider';
+
+export { default as GlobalStyles } from './GlobalStyles';
+export * from './GlobalStyles';

packages/material-ui-styled-engine-sc/src/index.js

@@ -12,5 +12,5 @@ export default function styled(tag, options) {
 }
 
 export { ThemeContext, keyframes } from 'styled-components';
-
 export { default as StylesProvider } from './StylesProvider';
+export { default as GlobalStyles } from './GlobalStyles';

packages/material-ui-styled-engine/src/GlobalStyles/GlobalStyles.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { Interpolation } from '@emotion/styled';
+
+export interface GlobalStylesProps {
+  defaultTheme?: object;
+  styles: Interpolation<any>;
+}
+
+export default function GlobalStyles(props: GlobalStylesProps): React.ReactElement;