[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/hooks.test.tsx

@@ -7,15 +7,18 @@
  */
 
 import React from 'react';
-import { render } from '@testing-library/react';
+import { render, act } from '@testing-library/react';
 import { renderHook } from '../../test/rtl';
 
+import { EuiProvider } from '../../components';
+
 import { setEuiDevProviderWarning } from './warning';
 import {
   useEuiTheme,
   UseEuiTheme,
   withEuiTheme,
   RenderWithEuiTheme,
+  useEuiThemeCSSVariables,
 } from './hooks';
 
 describe('useEuiTheme', () => {
@@ -82,3 +85,21 @@ describe('RenderWithEuiTheme', () => {
     );
   });
 });
+
+describe('useEuiThemeCSSVariables', () => {
+  it('returns CSS variable related state setters/getters', () => {
+    const { result } = renderHook(useEuiThemeCSSVariables, {
+      wrapper: EuiProvider,
+    });
+    expect(result.current.globalCSSVariables).toBeUndefined();
+    expect(result.current.themeCSSVariables).toBeUndefined();
+
+    act(() => {
+      result.current.setNearestThemeCSSVariables({ '--hello': 'world' });
+    });
+
+    // In this case, the nearest theme is the global one, so it should set both
+    expect(result.current.globalCSSVariables).toEqual({ '--hello': 'world' });
+    expect(result.current.themeCSSVariables).toEqual({ '--hello': 'world' });
+  });
+});

src/services/theme/hooks.tsx

@@ -13,6 +13,7 @@ import {
   EuiModificationsContext,
   EuiColorModeContext,
   defaultComputedTheme,
+  EuiNestedThemeContext,
 } from './context';
 import { emitEuiProviderWarning } from './warning';
 import {
@@ -95,3 +96,23 @@ export const RenderWithEuiTheme = <T extends {} = {}>({
   const theme = useEuiTheme<T>();
   return children(theme);
 };
+
+/**
+ * Minor syntactical sugar hook for theme CSS variables.
+ * Primarily meant for internal EUI usage.
+ */
+export const useEuiThemeCSSVariables = () => {
+  const {
+    setGlobalCSSVariables,
+    globalCSSVariables,
+    setNearestThemeCSSVariables,
+    themeCSSVariables,
+  } = useContext(EuiNestedThemeContext);
+
+  return {
+    setGlobalCSSVariables,
+    globalCSSVariables,
+    setNearestThemeCSSVariables,
+    themeCSSVariables,
+  };
+};

src/services/theme/index.ts

@@ -14,7 +14,12 @@ export {
   EuiColorModeContext,
 } from './context';
 export type { UseEuiTheme, WithEuiThemeProps } from './hooks';
-export { useEuiTheme, withEuiTheme, RenderWithEuiTheme } from './hooks';
+export {
+  useEuiTheme,
+  withEuiTheme,
+  RenderWithEuiTheme,
+  useEuiThemeCSSVariables,
+} from './hooks';
 export type { EuiThemeProviderProps } from './provider';
 export { EuiThemeProvider } from './provider';
 export { getEuiDevProviderWarning, setEuiDevProviderWarning } from './warning';

src/services/theme/provider.stories.tsx

@@ -0,0 +1,98 @@
+/*
+ * 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, useEffect } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { useEuiThemeCSSVariables } from './hooks';
+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 } =
+    useEuiThemeCSSVariables();
+
+  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"}');
+    });
+  });
 });