[Emotion] Logical property, padding, and background color utilities

src-docs/src/views/theme/color/_color_js.tsx

@@ -4,7 +4,18 @@ import { css } from '@emotion/react';
 import { transparentize, useEuiTheme } from '../../../../../src/services';
 import { getPropsFromComponent } from '../../../services/props/get_props';
 
-import { EuiCode, EuiColorPickerSwatch } from '../../../../../src';
+import {
+  useEuiBackgroundColorCSS,
+  EuiCode,
+  EuiColorPickerSwatch,
+  EuiSpacer,
+  EuiText,
+  useEuiBackgroundColor,
+  useEuiPaddingSize,
+  BACKGROUND_COLORS,
+  euiBackgroundColor,
+  useEuiPaddingCSS,
+} from '../../../../../src';
 
 import { EuiThemeColors, ThemeRowType } from '../_props';
 
@@ -215,3 +226,88 @@ export const SpecialJS: FunctionComponent<ThemeRowType> = ({ description }) => {
     </>
   );
 };
+
+export const UtilsJS = () => {
+  const euiTheme = useEuiTheme();
+
+  return (
+    <>
+      <EuiText grow={false}>
+        <h3>Background colors</h3>
+        <p>
+          To all but ensure proper contrast of text to background, we recommend
+          using our pre-defined shades of background colors based on the
+          EuiTheme brand colors. You can also use{' '}
+          <Link to="/layout/panel">
+            <strong>EuiPanel</strong>
+          </Link>{' '}
+          for the same effect plus more options like padding and rounded
+          corners.
+        </p>
+      </EuiText>
+
+      <EuiSpacer size="l" />
+
+      <ThemeExample
+        title={<code>{'useEuiBackgroundColorCSS()[color]'}</code>}
+        description={
+          <>
+            <p>
+              Returns an object of the available color keys containing the css
+              string of the computed background version for the given{' '}
+              <EuiCode language="sass">color</EuiCode>.
+            </p>
+            <p>
+              This is best used to map component prop styles to padding output.
+            </p>
+          </>
+        }
+        example={
+          <p css={[useEuiBackgroundColorCSS().accent, useEuiPaddingCSS().l]}>
+            <code>{useEuiBackgroundColorCSS().accent}</code>
+          </p>
+        }
+        snippetLanguage="tsx"
+        snippet={`const colorStyles = useEuiBackgroundColorCSS();
+const cssStyles = [colorStyles['accent']];
+
+<span css={cssStyles}>
+  /* Your content */
+</span>`}
+      />
+
+      <ThemeExample
+        title={<code>useEuiBackgroundColor(color)</code>}
+        description={
+          <p>
+            Returns just the computed background color for the given{' '}
+            <EuiCode language="sass">color</EuiCode>.
+          </p>
+        }
+        example={
+          <p
+            css={css`
+              background: ${useEuiBackgroundColor('subdued')};
+              padding: ${useEuiPaddingSize('l')};
+            `}
+          >
+            <code>{useEuiBackgroundColor('subdued')}</code>
+          </p>
+        }
+        snippetLanguage="emotion"
+        snippet={"background: ${useEuiBackgroundColor('subdued')};"}
+      />
+
+      <ThemeValuesTable
+        items={BACKGROUND_COLORS.map((color) => {
+          return {
+            id: color,
+            token: `useEuiBackgroundColor('${color}')`,
+            value: euiBackgroundColor(color, euiTheme),
+          };
+        })}
+        render={(item) => <EuiColorPickerSwatch color={item.value} disabled />}
+      />
+    </>
+  );
+};

src-docs/src/views/theme/color/_contrast_js.tsx

@@ -22,16 +22,20 @@ const textVariants = [...brandTextKeys, ...textColors];
 
 type ColorSection = {
   color: keyof _EuiThemeColorsMode;
+  colorValue?: string;
   minimumContrast: string | number;
   showTextVariants: boolean;
   matchPanelColor?: boolean;
+  hookName?: string;
 };
 
 export const ColorSectionJS: FunctionComponent<ColorSection> = ({
   color,
+  colorValue: _colorValue,
   minimumContrast,
   showTextVariants,
   matchPanelColor,
+  hookName,
 }) => {
   const { euiTheme } = useEuiTheme();
   const colorsForContrast = showTextVariants ? textVariants : allowedColors;
@@ -40,35 +44,38 @@ export const ColorSectionJS: FunctionComponent<ColorSection> = ({
     return brandKeys.includes(color) || brandTextKeys.includes(color);
   }
 
+  const colorValue = _colorValue || euiTheme.colors[color];
+
   return (
     <EuiPanel
       color="transparent"
       hasBorder={false}
       paddingSize={matchPanelColor ? 'l' : 'none'}
       style={{
-        background: matchPanelColor ? euiTheme.colors[color] : undefined,
+        background: matchPanelColor ? colorValue : undefined,
       }}
     >
       <EuiText size="xs">
         <EuiFlexGrid columns={2} direction="column" gutterSize="s">
-          {showTextVariants && colorIsCore(color) && (
+          {showTextVariants && colorIsCore(colorValue) && (
             <ColorsContrastItem
               foreground={`${color}Text`}
               background={'body'}
               minimumContrast={minimumContrast}
             />
           )}
           {colorsForContrast.map((color2) => {
-            if (colorIsCore(color) && colorIsCore(color2)) {
+            if (colorIsCore(colorValue) && colorIsCore(color2)) {
               // i.e. don't render if both are core colors
               return;
             }
             return (
               <ColorsContrastItem
                 foreground={color2}
-                background={color}
+                background={_colorValue ? colorValue : color}
                 key={color2}
                 minimumContrast={minimumContrast}
+                styleString={hookName && `${hookName}('${color}')`}
               />
             );
           })}
@@ -82,18 +89,22 @@ type ColorsContrastItem = {
   foreground: string;
   background: string;
   minimumContrast: string | number;
+  styleString?: string;
 };
 
 const ColorsContrastItem: FunctionComponent<ColorsContrastItem> = ({
   foreground,
   background,
   minimumContrast,
+  styleString,
 }) => {
   const { euiTheme } = useEuiTheme();
-  const backgroundColor =
+  const backgroundColorIsToken =
     euiTheme.colors[background as keyof _EuiThemeColorsMode];
-  const foregroundColor =
+  const backgroundColor = backgroundColorIsToken || background;
+  const foregroundColorIsToken =
     euiTheme.colors[foreground as keyof _EuiThemeColorsMode];
+  const foregroundColor = foregroundColorIsToken || foreground;
   const backgroundIsBody = background === 'body';
 
   const contrast = chroma.contrast(backgroundColor, foregroundColor);
@@ -107,14 +118,17 @@ const ColorsContrastItem: FunctionComponent<ColorsContrastItem> = ({
     foreground
   );
 
+  const backgroundStyleString = styleString || `euiTheme.colors.${background}`;
+
   const contrastIsAcceptableToCopy = contrast >= 3;
   const textToCopy = backgroundIsBody
     ? `color: $\{euiTheme.colors.${foreground}};`
-    : `background-color: $\{euiTheme.colors.${background}};
+    : `background-color: $\{${backgroundStyleString}};
 color: $\{euiTheme.colors.${foreground}};`;
+
   const beforeMessage = contrastIsAcceptableToCopy ? (
     <small>
-      <code>{`euiTheme.colors.${foreground} / euiTheme.colors.${background}`}</code>
+      <code>{`euiTheme.colors.${foreground} / ${backgroundStyleString}`}</code>
       <EuiHorizontalRule margin="xs" />
       <kbd>Click</kbd> to copy CSS-in-JS configuration
     </small>
@@ -127,7 +141,7 @@ color: $\{euiTheme.colors.${foreground}};`;
   return (
     <EuiFlexItem className="eui-textCenter">
       <EuiCopy
-        anchorClassName="eui-displayBlock"
+        display="block"
         title={
           <span>
             {contrastRatingBadge} Contrast is {contrast.toFixed(1)}

src-docs/src/views/theme/color/colors.tsx

@@ -1,6 +1,6 @@
 import React, { useContext, useMemo, useState } from 'react';
 
-import { EuiCode, EuiSpacer, EuiText } from '../../../../../src';
+import { EuiCallOut, EuiCode, EuiSpacer, EuiText } from '../../../../../src';
 
 // @ts-ignore Importing from JS
 import { GuidePage } from '../../../components/guide_page';
@@ -11,7 +11,7 @@ import { ThemeNotice } from '../_components/_theme_notice';
 // @ts-ignore Importing JS
 import ColorsContrast from './contrast';
 
-import { BrandJS, ShadeJS, SpecialJS, TextJS } from './_color_js';
+import { BrandJS, ShadeJS, SpecialJS, TextJS, UtilsJS } from './_color_js';
 import { Link } from 'react-router-dom';
 import { BrandSass, ShadeSass, SpecialSass, TextSass } from './_color_sass';
 
@@ -32,6 +32,7 @@ export const colorsSections = [
   { title: 'Text colors', id: 'text-colors' },
   { title: 'Shades', id: 'shades' },
   { title: 'Special colors', id: 'special-colors' },
+  { title: 'Utilities', id: 'utilities' },
 ];
 
 export default () => {
@@ -97,6 +98,12 @@ export default () => {
     return <SpecialJS description={description} />;
   }, [showSass]);
 
+  const utilsContent = useMemo(() => {
+    if (showSass)
+      return <EuiCallOut title="Utilities only available for Emotion." />;
+    return <UtilsJS />;
+  }, [showSass]);
+
   return (
     <GuidePage
       isBeta={!showSass && !selectedTabId.includes('contrast')}
@@ -155,7 +162,6 @@ export default () => {
           <EuiSpacer size="xl" />
 
           <EuiText grow={false}>
-            {' '}
             <h2
               id={`${colorsSections[1].id}`}
             >{`${colorsSections[1].title}`}</h2>
@@ -182,7 +188,6 @@ export default () => {
           <EuiSpacer size="xl" />
 
           <EuiText grow={false}>
-            {' '}
             <h2
               id={`${colorsSections[2].id}`}
             >{`${colorsSections[2].title}`}</h2>
@@ -199,7 +204,6 @@ export default () => {
           <EuiSpacer size="xl" />
 
           <EuiText grow={false}>
-            {' '}
             <h2
               id={`${colorsSections[3].id}`}
             >{`${colorsSections[3].title}`}</h2>
@@ -209,6 +213,18 @@ export default () => {
           <EuiSpacer size="xl" />
 
           {specialContent}
+
+          <EuiSpacer size="xl" />
+
+          <EuiText grow={false}>
+            <h2
+              id={`${colorsSections[4].id}`}
+            >{`${colorsSections[4].title}`}</h2>
+          </EuiText>
+
+          <EuiSpacer size="xl" />
+
+          {utilsContent}
         </>
       )}
     </GuidePage>

src-docs/src/views/theme/color/contrast.tsx

@@ -7,7 +7,9 @@ import {
   EuiLink,
   EuiTitle,
   EuiPanel,
-} from '../../../../../src/components';
+  EuiCallOut,
+  EuiCode,
+} from '../../../../../src';
 
 import {
   ColorSectionSass,
@@ -21,6 +23,11 @@ import { brandKeys, shadeKeys } from './_color_js';
 import { ContrastSlider } from './_contrast_slider';
 import { ratingAA } from './_contrast_utilities';
 import { _EuiThemeColorsMode } from '../../../../../src/global_styling/variables/colors';
+import {
+  BACKGROUND_COLORS,
+  EuiBackgroundColor,
+  useEuiBackgroundColor,
+} from '../../../../../src/global_styling';
 
 export default () => {
   const [showTextVariants, setShowTextVariants] = useState(true);
@@ -181,6 +188,45 @@ export default () => {
                 );
               })}
         </EuiPanel>
+
+        <EuiSpacer size="xxl" />
+
+        <EuiText grow={false}>
+          <h3>Background colors</h3>
+          <p>
+            These background colors are pre-defined shades of the brand colors.
+            They are recalled by using the hook{' '}
+            <EuiCode>useEuiBackgroundColor(color)</EuiCode>.
+          </p>
+        </EuiText>
+
+        <EuiSpacer />
+
+        <EuiPanel color="subdued">
+          {showSass ? (
+            <EuiCallOut title="Background colors only exist for CSS-in-JS styling." />
+          ) : (
+            BACKGROUND_COLORS.map((color: string) => {
+              return (
+                color !== 'transparent' && (
+                  <React.Fragment key={color}>
+                    <ColorSectionJS
+                      key={color}
+                      color={color as keyof _EuiThemeColorsMode}
+                      colorValue={useEuiBackgroundColor(
+                        color as EuiBackgroundColor
+                      )}
+                      hookName="useEuiBackgroundColor"
+                      minimumContrast={contrastValue}
+                      showTextVariants={showTextVariants}
+                    />
+                    <EuiSpacer />
+                  </React.Fragment>
+                )
+              );
+            })
+          )}
+        </EuiPanel>
       </div>
     </>
   );