feat: add refactored getColor utility (#1763)

.github/CONTRIBUTING.md

@@ -48,7 +48,9 @@ on your system. After you clone this repo, run `npm install` to install
 dependencies needed for development. After installation, the following
 commands are available:
 
-- `npm start` to launch Storybook with live reload.
+- `npm start` to launch Storybook with live reload. Use `PACKAGE=dirname npm start`
+  (where `dirname` is a package directory name) to limit Storybook launch to the
+  given Garden package.
 - `npm test` to run Jest testing.
 - `npm run lint` to enforce consistent JavaScript, CSS, and
   markdown code conventions across all component packages. Note this is

.storybook/preview.js

@@ -8,11 +8,11 @@
 import React from 'react';
 import styled, { createGlobalStyle } from 'styled-components';
 import { create } from '@storybook/theming/create';
-import { ThemeProvider, DEFAULT_THEME, getColorV8 } from '../packages/theming/src';
+import { ThemeProvider, DEFAULT_THEME, getColor } from '../packages/theming/src';
 
 const DARK_THEME = { ...DEFAULT_THEME, colors: { ...DEFAULT_THEME.colors, base: 'dark' } };
-const DARK = getColorV8('foreground', 600 /* default shade */, DARK_THEME);
-const LIGHT = getColorV8('background', 600 /* default shade */, DEFAULT_THEME);
+const DARK = getColor({ theme: DARK_THEME, variable: 'background.default' });
+const LIGHT = getColor({ theme: DEFAULT_THEME, variable: 'background.default' });
 
 export const parameters = {
   actions: { argTypesRegex: '^on[A-Z].*' },
@@ -36,7 +36,7 @@ export const parameters = {
 
 const GlobalPreviewStyling = createGlobalStyle`
   body {
-    background-color: ${p => getColorV8('background', 600 /* default shade */, p.theme)};
+    background-color: ${p => getColor({ theme: p.theme, variable: 'background.default' })};
     /* stylelint-disable-next-line declaration-no-important */
     padding: 0 !important;
     font-family: ${p => p.theme.fonts.system};
@@ -65,8 +65,6 @@ const withThemeProvider = (story, context) => {
       : context.parameters.backgrounds.default === 'dark'
   ) {
     colors.base = 'dark';
-    colors.background = getColorV8('neutralHue', 900, DEFAULT_THEME);
-    colors.foreground = getColorV8('neutralHue', 200, DEFAULT_THEME);
   }
 
   const theme = { ...DEFAULT_THEME, colors, rtl };

docs/migration.md

@@ -182,6 +182,9 @@ consider additional positioning prop support on a case-by-case basis.
   scheme to custom components that are not part of the Garden framework. It is
   recommended to utilize this stopgap measure until such components can be updated
   to leverage the full capabilities of v9 `getColor`.
+- Utility function `getColor` has been refactored with a signature that supports
+  v9 light/dark modes. Replace usage with `getColorV8` until custom components can
+  be upgraded to utilize the new `getColor` function.
 - Utility function `getDocument` has been removed. Use `useDocument` instead.
 - Utility function `isRtl` has been removed. Use `props.theme.rtl` instead.
 - The following exports have changed:

packages/theming/demo/stories/GetColorStory.tsx

@@ -6,25 +6,118 @@
  */
 
 import React from 'react';
-import styled from 'styled-components';
-import { Story } from '@storybook/react';
-import { DEFAULT_THEME, getColorV8 } from '@zendeskgarden/react-theming';
+import { StoryFn } from '@storybook/react';
+import styled, { DefaultTheme, useTheme } from 'styled-components';
+import { IGardenTheme, getColor } from '@zendeskgarden/react-theming';
+import { Tag } from '@zendeskgarden/react-tags';
 
-interface IArgs {
-  hue: string;
-  shade: number;
-  transparency?: number;
-}
+const toBackground = (theme: DefaultTheme, backgroundColor: string) => {
+  const color = getColor({ hue: 'neutralHue', shade: 300, theme });
+  const size = 26;
+  const dimensions = `${size}px ${size}px`;
+  const positionX1 = theme.rtl ? '100%' : '0';
+  const positionX2 = theme.rtl ? `calc(100% - ${size / 2}px)` : `${size / 2}px`;
+  const position1 = `${positionX1} 0`;
+  const position2 = `${positionX2} ${size / 2}px`;
+  const position3 = `${positionX2} 0`;
+  const position4 = `${positionX1} ${size / -2}px`;
 
-const StyledDiv = styled.div<IArgs>`
-  background-color: ${props =>
-    getColorV8(
-      props.hue,
-      props.shade,
-      DEFAULT_THEME,
-      props.transparency ? props.transparency / 100 : undefined
-    )};
+  return `
+    linear-gradient(${backgroundColor}, ${backgroundColor}), 
+    linear-gradient(45deg, ${color} 25%, transparent 25%) ${position1} / ${dimensions} repeat,
+    linear-gradient(45deg, transparent 75%, ${color} 75%) ${position2} / ${dimensions} repeat,
+    linear-gradient(135deg, ${color} 25%, transparent 25%) ${position3} / ${dimensions} repeat,
+    linear-gradient(135deg, transparent 75%, ${color} 75%) ${position4} / ${dimensions} repeat
+  `;
+};
+
+const StyledDiv = styled.div<{ background: string }>`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: ${p => p.background};
   height: 208px;
 `;
 
-export const GetColorStory: Story<IArgs> = args => <StyledDiv {...args} />;
+interface IColorProps {
+  dark?: object;
+  hue?: string;
+  light?: object;
+  offset?: number;
+  shade?: number;
+  theme: IGardenTheme;
+  transparency?: number;
+  variable?: string;
+}
+
+const Color = ({ dark, hue, light, offset, shade, theme, transparency, variable }: IColorProps) => {
+  let background;
+  let tag;
+
+  try {
+    const backgroundColor = getColor({
+      dark,
+      hue,
+      light,
+      offset,
+      shade,
+      theme,
+      transparency: transparency ? transparency / 100 : undefined,
+      variable
+    });
+
+    background = toBackground(theme, backgroundColor);
+    tag = (
+      <Tag hue={getColor({ theme, variable: 'background.default' })} size="large">
+        {backgroundColor}
+      </Tag>
+    );
+  } catch (error) {
+    background = 'transparent';
+    tag = (
+      <Tag hue="red" size="large">
+        {error instanceof Error ? error.message : String(error)}
+      </Tag>
+    );
+  }
+
+  return <StyledDiv background={background}>{tag}</StyledDiv>;
+};
+
+interface IArgs extends Omit<IColorProps, 'theme'> {
+  theme: {
+    colors: Omit<IGardenTheme['colors'], 'base'>;
+    palette: IGardenTheme['palette'];
+  };
+}
+
+export const GetColorStory: StoryFn<IArgs> = ({
+  dark,
+  hue,
+  light,
+  offset,
+  shade,
+  theme: _theme,
+  transparency,
+  variable
+}) => {
+  const parentTheme = useTheme();
+  const theme = {
+    ...parentTheme,
+    colors: { ..._theme.colors, base: parentTheme.colors.base },
+    palette: _theme.palette
+  };
+
+  return (
+    <Color
+      dark={dark}
+      hue={hue}
+      light={light}
+      offset={offset}
+      shade={shade}
+      theme={theme}
+      transparency={transparency}
+      variable={variable}
+    />
+  );
+};

packages/theming/demo/utilities.stories.mdx

@@ -48,10 +48,20 @@ import README from '../README.md';
     name="getColor()"
     args={{
       hue: 'primaryHue',
-      shade: 600
+      theme: {
+        colors: Object.fromEntries(
+          Object.entries(DEFAULT_THEME.colors).filter(([key]) => key !== 'base')
+        ),
+        palette: DEFAULT_THEME.palette
+      }
     }}
     argTypes={{
-      transparency: { control: { type: 'range', min: 1 } }
+      dark: { control: { type: 'object' } },
+      light: { control: { type: 'object' } },
+      offset: { control: { type: 'number' } },
+      shade: { control: { type: 'number' } },
+      transparency: { control: { type: 'range', min: 1 } },
+      variable: { control: { type: 'text' } }
     }}
   >
     {args => <GetColorStory {...args} />}

packages/theming/package.json

@@ -24,6 +24,8 @@
     "@floating-ui/react-dom": "^2.0.0",
     "@zendeskgarden/container-focusvisible": "^2.0.0",
     "@zendeskgarden/container-utilities": "^2.0.0",
+    "chroma-js": "^2.4.2",
+    "lodash.get": "^4.4.2",
     "lodash.memoize": "^4.1.2",
     "polished": "^4.0.0",
     "prop-types": "^15.5.7"
@@ -34,6 +36,8 @@
     "styled-components": "^4.2.0 || ^5.3.1"
   },
   "devDependencies": {
+    "@types/chroma-js": "2.4.4",
+    "@types/lodash.get": "4.4.9",
     "@types/lodash.memoize": "4.1.9"
   },
   "keywords": [

packages/theming/src/index.ts

@@ -11,7 +11,8 @@ export { default as PALETTE } from './elements/palette';
 export { default as PALETTE_V8 } from './elements/palette/v8';
 export { default as retrieveComponentStyles } from './utils/retrieveComponentStyles';
 export { getArrowPosition } from './utils/getArrowPosition';
-export { getColorV8 as getColor, getColorV8 } from './utils/getColorV8';
+export { getColor } from './utils/getColor';
+export { getColorV8 } from './utils/getColorV8';
 export { getFloatingPlacements } from './utils/getFloatingPlacements';
 export { getFocusBoxShadow } from './utils/getFocusBoxShadow';
 export { default as getLineHeight } from './utils/getLineHeight';

packages/theming/src/types/index.ts

@@ -45,7 +45,7 @@ export const PLACEMENT = [
 
 export type Placement = (typeof PLACEMENT)[number];
 
-type Hue = Record<number | string, string> | string;
+export type Hue = Record<number | string, string> | string;
 
 export interface IGardenTheme {
   rtl: boolean;

packages/theming/src/utils/focusStyles.spec.tsx

@@ -9,7 +9,7 @@ import React from 'react';
 import { render } from 'garden-test-utils';
 import styled, { ThemeProps, DefaultTheme, CSSObject } from 'styled-components';
 import { focusStyles } from './focusStyles';
-import { Hue } from './getColorV8';
+import { Hue } from '../types';
 import DEFAULT_THEME from '../elements/theme';
 import PALETTE_V8 from '../elements/palette/v8';