[EuiThemeProvider] Add context & state required for theme CSS variables architecture

src/services/theme/__snapshots__/provider.test.tsx.snap

@@ -1,5 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`EuiThemeProvider CSS variables allows child components to set non-global theme CSS variables 1`] = `
+<span
+  class="euiThemeProvider emotion-euiCSSVariables-euiColorMode--colorClassName"
+/>
+`;
+
 exports[`EuiThemeProvider nested EuiThemeProviders allows avoiding the extra span wrapper with \`wrapperProps.cloneElement\` 1`] = `
 <div>
   Top-level provider

src/services/theme/context.ts

@@ -34,4 +34,6 @@ export const EuiNestedThemeContext = createContext<EuiThemeNested>({
   hasDifferentColorFromGlobalTheme: false,
   bodyColor: '',
   colorClassName: '',
+  setGlobalCSSVariables: () => {},
+  setNearestThemeCSSVariables: () => {},
 });

src/services/theme/provider.stories.tsx

@@ -0,0 +1,99 @@
+/*
+ * 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.
+ */
+
+import React, { FunctionComponent, useContext, useEffect } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { EuiNestedThemeContext } from './context';
+import { EuiThemeProvider, EuiThemeProviderProps } from './provider';
+
+const meta: Meta<EuiThemeProviderProps<{}>> = {
+  title: 'EuiThemeProvider',
+  component: EuiThemeProvider,
+};
+
+export default meta;
+type Story = StoryObj<EuiThemeProviderProps<{}>>;
+
+export const WrapperCloneElement: Story = {
+  render: () => (
+    <>
+      <EuiThemeProvider wrapperProps={{ cloneElement: true }}>
+        <main className="clonedExample">
+          This example should only have 1 main wrapper rendered.
+        </main>
+      </EuiThemeProvider>
+    </>
+  ),
+};
+
+export const CSSVariablesNearest: Story = {
+  render: () => (
+    <>
+      <MockComponent color="red">
+        This component sets the nearest theme provider (the global theme) with a
+        red CSS variable color. Inspect the `:root` styles to see the variable
+        set.
+      </MockComponent>
+      <EuiThemeProvider>
+        <MockComponent color="blue">
+          This component sets the nearest local theme provider with a blue CSS
+          variable color. Inspect the parent theme wrapper to see the variable
+          set.
+        </MockComponent>
+      </EuiThemeProvider>
+    </>
+  ),
+};
+
+export const CSSVariablesGlobal: Story = {
+  render: () => (
+    <>
+      <MockComponent color="red">
+        This component sets the nearest theme provider (the global theme) with a
+        red CSS variable color. However, it should be overridden by the next
+        component.
+      </MockComponent>
+      <EuiThemeProvider>
+        <MockComponent color="blue" global={true}>
+          This component sets the global theme with a blue CSS variable color.
+          It should override the previous component. Inspect the `:root` styles
+          to see this behavior
+        </MockComponent>
+      </EuiThemeProvider>
+    </>
+  ),
+};
+
+/**
+ * Component for QA/testing purposes that mocks an EUI component
+ * that sets global or theme-level CSS variables
+ */
+const MockComponent: FunctionComponent<{
+  global?: boolean;
+  color: string;
+  children: any;
+}> = ({ global, color, children }) => {
+  const { setGlobalCSSVariables, setNearestThemeCSSVariables } = useContext(
+    EuiNestedThemeContext
+  );
+
+  useEffect(() => {
+    if (global) {
+      setGlobalCSSVariables({ '--testColor': color });
+    } else {
+      setNearestThemeCSSVariables({ '--testColor': color });
+    }
+  }, [global, color, setGlobalCSSVariables, setNearestThemeCSSVariables]);
+
+  return (
+    <p style={{ color: 'var(--testColor)', marginBlockEnd: '1em' }}>
+      {children}
+    </p>
+  );
+};

src/services/theme/provider.test.tsx

@@ -6,11 +6,12 @@
  * Side Public License, v 1.
  */
 
-import React from 'react';
+import React, { FunctionComponent, useContext, useEffect } from 'react';
 import { render } from '@testing-library/react'; // Note - don't use the EUI custom RTL `render`, as it auto-wraps an `EuiProvider`
 import { css } from '@emotion/react';
 
 import { EuiProvider } from '../../components/provider';
+import { EuiNestedThemeContext } from './context';
 import { EuiThemeProvider } from './provider';
 
 describe('EuiThemeProvider', () => {
@@ -136,4 +137,82 @@ describe('EuiThemeProvider', () => {
       expect(container.querySelector('.hello.world')).toBeTruthy();
     });
   });
+
+  describe('CSS variables', () => {
+    const MockEuiComponent: FunctionComponent<{ global?: boolean }> = ({
+      global,
+    }) => {
+      const {
+        globalCSSVariables,
+        setGlobalCSSVariables,
+        setNearestThemeCSSVariables,
+      } = useContext(EuiNestedThemeContext);
+
+      useEffect(() => {
+        if (global) {
+          setGlobalCSSVariables({ '--hello': 'global-world' });
+        } else {
+          setNearestThemeCSSVariables({ '--hello': 'world' });
+        }
+      }, [global, setGlobalCSSVariables, setNearestThemeCSSVariables]);
+
+      // Our current version of jsdom doesn't yet support :root (currently on v11,
+      // need to be on at least v20), so we'll mock something to assert on in the interim
+      return <>{JSON.stringify(globalCSSVariables)}</>;
+    };
+
+    const getThemeProvider = (container: HTMLElement) =>
+      container.querySelector('.euiThemeProvider')!;
+    const getThemeClassName = (container: HTMLElement) =>
+      getThemeProvider(container).className;
+
+    it('allows child components to set non-global theme CSS variables', () => {
+      const { container } = render(
+        <EuiProvider>
+          <EuiThemeProvider>
+            <MockEuiComponent />
+          </EuiThemeProvider>
+        </EuiProvider>
+      );
+      expect(getThemeClassName(container)).toContain('euiCSSVariables');
+      expect(container.firstChild).toHaveStyleRule('--hello', 'world');
+      expect(container.firstChild).toMatchSnapshot();
+    });
+
+    it('sets global CSS variables when the nearest theme provider is the top-level one', () => {
+      const { container } = render(
+        <EuiProvider>
+          <MockEuiComponent />
+        </EuiProvider>
+      );
+      expect(container.textContent).toContain('{"--hello":"world"}');
+    });
+
+    it('allows child components to set global CSS variables from any nested theme provider', () => {
+      const { container } = render(
+        <EuiProvider>
+          <EuiThemeProvider>
+            <MockEuiComponent global={true} />
+          </EuiThemeProvider>
+        </EuiProvider>
+      );
+      expect(getThemeClassName(container)).not.toContain('euiCSSVariables');
+      expect(container.textContent).toContain('{"--hello":"global-world"}');
+    });
+
+    it('can set both global and nearest theme variables without conflicting', () => {
+      const { container } = render(
+        <EuiProvider>
+          <MockEuiComponent />
+          <EuiThemeProvider>
+            <MockEuiComponent />
+            <MockEuiComponent global={true} />
+          </EuiThemeProvider>
+        </EuiProvider>
+      );
+      expect(getThemeClassName(container)).toContain('euiCSSVariables');
+      expect(getThemeProvider(container)).toHaveStyleRule('--hello', 'world');
+      expect(container.textContent).toContain('{"--hello":"global-world"}');
+    });
+  });
 });

src/services/theme/provider.tsx

@@ -12,14 +12,17 @@ import React, {
   useRef,
   useMemo,
   useState,
+  useCallback,
   PropsWithChildren,
   HTMLAttributes,
 } from 'react';
 import classNames from 'classnames';
 import { css } from '@emotion/css';
+import { Global, type CSSObject } from '@emotion/react';
 import isEqual from 'lodash/isEqual';
 
 import type { CommonProps } from '../../components/common';
+import { cloneElementWithCss } from '../emotion';
 
 import {
   EuiSystemContext,
@@ -63,7 +66,12 @@ export const EuiThemeProvider = <T extends {} = {}>({
   children,
   wrapperProps,
 }: EuiThemeProviderProps<T>) => {
-  const { isGlobalTheme, bodyColor } = useContext(EuiNestedThemeContext);
+  const {
+    isGlobalTheme,
+    bodyColor,
+    globalCSSVariables,
+    setGlobalCSSVariables,
+  } = useContext(EuiNestedThemeContext);
   const parentSystem = useContext(EuiSystemContext);
   const parentModifications = useContext(EuiModificationsContext);
   const parentColorMode = useContext(EuiColorModeContext);
@@ -137,6 +145,13 @@ export const EuiThemeProvider = <T extends {} = {}>({
     }
   }, [colorMode, system, modifications]);
 
+  const [themeCSSVariables, _setThemeCSSVariables] = useState<CSSObject>();
+  const setThemeCSSVariables = useCallback(
+    (variables: CSSObject) =>
+      _setThemeCSSVariables((previous) => ({ ...previous, ...variables })),
+    []
+  );
+
   const nestedThemeContext = useMemo(() => {
     return {
       isGlobalTheme: false, // The theme that determines the global body styles
@@ -148,8 +163,25 @@ export const EuiThemeProvider = <T extends {} = {}>({
         label: euiColorMode-${_colorMode};
         color: ${theme.colors.text};
       `,
+      setGlobalCSSVariables: isGlobalTheme
+        ? setThemeCSSVariables
+        : setGlobalCSSVariables,
+      globalCSSVariables: isGlobalTheme
+        ? themeCSSVariables
+        : globalCSSVariables,
+      setNearestThemeCSSVariables: setThemeCSSVariables,
+      themeCSSVariables: themeCSSVariables,
     };
-  }, [theme, isGlobalTheme, bodyColor, _colorMode]);
+  }, [
+    theme,
+    isGlobalTheme,
+    bodyColor,
+    _colorMode,
+    setGlobalCSSVariables,
+    globalCSSVariables,
+    setThemeCSSVariables,
+    themeCSSVariables,
+  ]);
 
   const renderedChildren = useMemo(() => {
     if (isGlobalTheme) {
@@ -161,9 +193,14 @@ export const EuiThemeProvider = <T extends {} = {}>({
       ...rest,
       className: classNames(className, nestedThemeContext.colorClassName),
     };
+    // Condition avoids rendering an empty Emotion selector if no
+    // theme-specific CSS variables have been set by child components
+    if (themeCSSVariables) {
+      props.css = { label: 'euiCSSVariables', ...themeCSSVariables };
+    }
 
     if (cloneElement) {
-      return React.cloneElement(children, {
+      return cloneElementWithCss(children, {
         ...props,
         className: classNames(children.props.className, props.className),
       });
@@ -177,21 +214,32 @@ export const EuiThemeProvider = <T extends {} = {}>({
         </span>
       );
     }
-  }, [isGlobalTheme, nestedThemeContext, wrapperProps, children]);
+  }, [
+    isGlobalTheme,
+    themeCSSVariables,
+    nestedThemeContext,
+    wrapperProps,
+    children,
+  ]);
 
   return (
-    <EuiColorModeContext.Provider value={colorMode}>
-      <EuiSystemContext.Provider value={system}>
-        <EuiModificationsContext.Provider value={modifications}>
-          <EuiThemeContext.Provider value={theme}>
-            <EuiNestedThemeContext.Provider value={nestedThemeContext}>
-              <EuiEmotionThemeProvider>
-                {renderedChildren}
-              </EuiEmotionThemeProvider>
-            </EuiNestedThemeContext.Provider>
-          </EuiThemeContext.Provider>
-        </EuiModificationsContext.Provider>
-      </EuiSystemContext.Provider>
-    </EuiColorModeContext.Provider>
+    <>
+      {isGlobalTheme && themeCSSVariables && (
+        <Global styles={{ ':root': themeCSSVariables }} />
+      )}
+      <EuiColorModeContext.Provider value={colorMode}>
+        <EuiSystemContext.Provider value={system}>
+          <EuiModificationsContext.Provider value={modifications}>
+            <EuiThemeContext.Provider value={theme}>
+              <EuiNestedThemeContext.Provider value={nestedThemeContext}>
+                <EuiEmotionThemeProvider>
+                  {renderedChildren}
+                </EuiEmotionThemeProvider>
+              </EuiNestedThemeContext.Provider>
+            </EuiThemeContext.Provider>
+          </EuiModificationsContext.Provider>
+        </EuiSystemContext.Provider>
+      </EuiColorModeContext.Provider>
+    </>
   );
 };

src/services/theme/types.ts

@@ -6,6 +6,8 @@
  * Side Public License, v 1.
  */
 
+import type { CSSObject } from '@emotion/react';
+
 import { RecursivePartial, ValueOf } from '../../components/common';
 import { _EuiThemeAnimation } from '../../global_styling/variables/animations';
 import { _EuiThemeBreakpoints } from '../../global_styling/variables/breakpoint';
@@ -99,4 +101,8 @@ export type EuiThemeNested = {
   hasDifferentColorFromGlobalTheme: boolean;
   bodyColor: string;
   colorClassName: string;
+  setGlobalCSSVariables: Function;
+  globalCSSVariables?: CSSObject;
+  setNearestThemeCSSVariables: Function;
+  themeCSSVariables?: CSSObject;
 };