[EuiProvider] Add globalStyles prop for customization

CHANGELOG.md

@@ -4,6 +4,8 @@
 - Added `lettering` glyph to `EuiIcon` ([#5525](https://github.com/elastic/eui/pull/5525))
 - Updated the outline color in `euiCustomControlFocused` mixin to use `$euiFocusRingColor` instead of `currentColor` ([#5479](https://github.com/elastic/eui/pull/5479))
 - Added `betaBadgeTooltipProps` to `EuiKeyPadMenuItem` to extend the wrapping `EuiToolTip` ([#5541](https://github.com/elastic/eui/pull/5541))
+- Added `globalStyles` prop to `EuiProvider` to allow for global style customization ([#5497](https://github.com/elastic/eui/pull/5497))
+- Exported `EuiGlobalStyles` component ([#5497](https://github.com/elastic/eui/pull/5497))
 
 **Bug fixes**
 

package.json

@@ -113,11 +113,11 @@
     "@elastic/charts": "^41.0.1",
     "@elastic/datemath": "^5.0.3",
     "@elastic/eslint-config-kibana": "^0.15.0",
-    "@emotion/babel-preset-css-prop": "^11.0.0",
-    "@emotion/cache": "^11.4.0",
-    "@emotion/eslint-plugin": "^11.0.0",
-    "@emotion/jest": "^11.1.0",
-    "@emotion/react": "^11.1.1",
+    "@emotion/babel-preset-css-prop": "^11.2.0",
+    "@emotion/cache": "^11.7.1",
+    "@emotion/eslint-plugin": "^11.7.0",
+    "@emotion/jest": "^11.7.1",
+    "@emotion/react": "^11.7.1",
     "@pmmmwh/react-refresh-webpack-plugin": "^0.5.3",
     "@svgr/core": "5.5.0",
     "@svgr/plugin-svgo": "^4.0.3",

src-docs/src/views/provider/provider_example.js

@@ -2,13 +2,18 @@ import React from 'react';
 import { Link } from 'react-router-dom';
 
 import {
-  EuiMarkdownFormat,
   EuiText,
   EuiProvider,
+  EuiCode,
+  EuiCodeBlock,
+  EuiLink,
+  EuiSpacer,
 } from '../../../../src/components';
+
 import { GuideSectionPropsTable } from '../../components/guide_section/guide_section_parts/guide_section_props_table';
 
-const providerSource = require('!!raw-loader!./provider.md').default;
+import Setup from './provider_setup';
+import GlobalStyles from './provider_styles';
 
 export const ProviderExample = {
   title: 'Provider',
@@ -28,8 +33,93 @@ export const ProviderExample = {
   ),
   sections: [
     {
-      wrapText: false,
-      text: <EuiMarkdownFormat>{providerSource}</EuiMarkdownFormat>,
+      title: 'Basic setup',
+      text: (
+        <EuiText>
+          <p>
+            For EUI to work correctly, set up <strong>EuiProvider</strong> at
+            the root of your application.
+          </p>
+
+          <Setup />
+
+          <p>
+            See{' '}
+            <EuiLink href="/#/theming/theme-provider">
+              <strong>EuiThemeProvider</strong>
+            </EuiLink>{' '}
+            for full documentation as all relevant props will pass through. For
+            instance, it&apos;s likely that you will want to implement color
+            mode switching at this level:
+          </p>
+
+          <EuiCodeBlock language="tsx" fontSize="m" isCopyable>
+            {"<EuiProvider colorMode={isDark ? 'dark' : 'light'} />"}
+          </EuiCodeBlock>
+
+          <EuiSpacer size="s" />
+
+          <p>
+            It is not recommended to recreate the functionality of{' '}
+            <strong>EuiProvider</strong> by composing its constituent parts.
+            More context, functionality, and configurations will be added to{' '}
+            <strong>EuiProvider</strong> in future releases. Nested instances of{' '}
+            <EuiLink href="/#/theming/theme-provider">
+              <strong>EuiThemeProvider</strong>
+            </EuiLink>
+            , however, are valid.
+          </p>
+        </EuiText>
+      ),
+    },
+    {
+      title: 'Global styles',
+      text: (
+        <EuiText>
+          <p>
+            The provider includes general reset and global styles, applied via
+            Emotion. These only need to be applied <strong>once</strong> so to
+            prevent these styles from loading in nested instances of the
+            provider, pass
+            <EuiCode>{'globalStyles={false}'}</EuiCode>.
+          </p>
+
+          <h3>
+            <EuiCode>@emotion/cache</EuiCode> and style injection location
+          </h3>
+          <p>
+            In the case that your app has its own static stylesheet, the global
+            styles may not be injected into the correct location in the{' '}
+            <EuiCode>{'<head>'}</EuiCode>, causing unintentional overrides or
+            unapplied styles.{' '}
+            <EuiLink href="https://emotion.sh/docs/@emotion/cache" external>
+              The <strong>@emotion/cache</strong> library
+            </EuiLink>{' '}
+            provides configuration options that help with specifying the
+            injection location. We recommend using a{' '}
+            <EuiCode>{'<meta>'}</EuiCode> tag to achieve this.
+          </p>
+
+          <GlobalStyles />
+
+          <p>
+            Any other options available with{' '}
+            <EuiLink
+              href="https://emotion.sh/docs/@emotion/cache#createcache"
+              external
+            >
+              the <strong>createCache</strong> API
+            </EuiLink>{' '}
+            will be respected by EUI.
+          </p>
+
+          <p>
+            Note that EUI does not include the <EuiCode>@emotion/cache</EuiCode>{' '}
+            library, so you will need to add it to your application
+            dependencies.
+          </p>
+        </EuiText>
+      ),
     },
     {
       title: 'EuiProvider props',

src-docs/src/views/provider/provider_setup.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+
+import { EuiCodeBlock, useEuiTheme, isLegacyTheme } from '../../../../src';
+
+export default () => {
+  const { euiTheme, colorMode } = useEuiTheme();
+  const isLegacy = isLegacyTheme(euiTheme.themeName);
+
+  return (
+    <EuiCodeBlock language="tsx" fontSize="m" isCopyable>
+      {`import { EuiProvider } from '@elastic/eui';
+
+const MyApp = () => (
+  <EuiProvider${isLegacy ? ' theme={null}' : ''}${
+        colorMode === 'DARK' ? ' colorMode="dark"' : ''
+      }>
+    {/* Content */}
+  </EuiProvider>
+);`}
+    </EuiCodeBlock>
+  );
+};

src-docs/src/views/provider/provider_styles.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+
+import {
+  EuiCodeBlock,
+  EuiSpacer,
+  useEuiTheme,
+  isLegacyTheme,
+} from '../../../../src';
+
+export default () => {
+  const { euiTheme, colorMode } = useEuiTheme();
+  const isLegacy = isLegacyTheme(euiTheme.themeName);
+
+  return (
+    <>
+      <EuiCodeBlock language="html" fontSize="m" isCopyable>
+        {!isLegacy
+          ? `<!-- index.html -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>My App</title>
+    <meta name="global-style-insert">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>`
+          : `<!-- index.html -->
+<!-- No template modifications necessary when using the Legacy theme -->`}
+      </EuiCodeBlock>
+
+      <EuiSpacer size="s" />
+
+      <EuiCodeBlock language="jsx" fontSize="m" isCopyable>
+        {`// App.js
+import { EuiProvider } from '@elastic/eui'
+${
+  !isLegacy
+    ? `import createCache from '@emotion/cache';
+
+const cache = createCache({
+  key: 'myApp',
+  container: document.querySelector('meta[name="global-style-insert"]'),
+});
+`
+    : ''
+}
+<EuiProvider${isLegacy ? ' theme={null}' : ''}${
+          colorMode === 'DARK' ? ' colorMode="dark"' : ''
+        }${!isLegacy ? ' cache={cache}' : ''}>
+  {/* Content */}
+</EuiProvider>
+  `}
+      </EuiCodeBlock>
+    </>
+  );
+};

src/components/provider/__snapshots__/provider.test.tsx.snap

@@ -1496,6 +1496,7 @@ exports[`EuiProvider providing an @emotion cache config applies the cache to glo
           "before": null,
           "container": <head />,
           "ctr": 0,
+          "insertionPoint": undefined,
           "isSpeedy": false,
           "key": "testing",
           "nonce": undefined,

src/components/provider/provider.tsx

@@ -9,10 +9,7 @@
 import React, { PropsWithChildren } from 'react';
 import { CacheProvider, EmotionCache } from '@emotion/react';
 
-import {
-  EuiGlobalStyles,
-  EuiGlobalStylesProps,
-} from '../../global_styling/reset/global_styles';
+import { EuiGlobalStyles, EuiGlobalStylesProps } from '../../global_styling';
 import {
   EuiThemeProvider,
   EuiThemeProviderProps,
@@ -28,24 +25,33 @@ export interface EuiProviderProps<T>
    * Pass `null` to remove all theming including global reset
    */
   theme?: EuiThemeSystem | null;
+  /**
+   * Provide global styles via `@emotion/react` `Global` for your custom theme.
+   * Pass `false` to remove the default EUI global styles.
+   */
+  globalStyles?: false | ((params: any) => JSX.Element | null);
+  /**
+   * Provide a cache configuration from `@emotion/cache`
+   */
   cache?: EmotionCache;
 }
 
 export const EuiProvider = <T extends {} = {}>({
   cache,
   theme = EuiThemeAmsterdam,
+  globalStyles: GlobalStyles = EuiGlobalStyles,
   colorMode,
   modify,
   children,
 }: PropsWithChildren<EuiProviderProps<T>>) => {
-  return theme !== null ? (
+  return theme !== null && GlobalStyles !== false ? (
     <EuiThemeProvider theme={theme} colorMode={colorMode} modify={modify}>
       {cache ? (
         <CacheProvider value={cache}>
-          <EuiGlobalStyles />
+          <GlobalStyles />
         </CacheProvider>
       ) : (
-        <EuiGlobalStyles />
+        <GlobalStyles />
       )}
       {children}
     </EuiThemeProvider>

src/global_styling/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export * from './reset/global_styles';

src/index.ts

@@ -10,3 +10,4 @@ export * from './components';
 export * from './services';
 export * from './utils';
 export * from './themes';
+export * from './global_styling';