@workday/canvas-kit-react 7.1.4 → 7.2.0-427-next.2

package/common/index.ts

@@ -7,3 +7,4 @@ export * from './lib/utils';
 export * from './lib/CanvasProvider';
 export * from './lib/InputProvider';
 export * from './lib/EllipsisText';
+export * from './lib/responsive/useResponsiveContainerStyles';

package/common/lib/EllipsisText.tsx

@@ -1,5 +1,7 @@
+import React from 'react';
 import styled, {CSSObject} from '@emotion/styled';
-import {ElementComponent} from '..';
+
+import {createComponent} from './utils';
 
 export const ellipsisStyles: CSSObject = {
   whiteSpace: 'nowrap',
@@ -7,5 +9,11 @@ export const ellipsisStyles: CSSObject = {
   overflow: 'hidden',
 };
 
-// Recast as an `ElementComponent` due to better type support for `as` and `ref`
-export const EllipsisText = (styled('span')(ellipsisStyles) as any) as ElementComponent<'span', {}>;
+const StyledEllipsisComponent = styled('span')(ellipsisStyles);
+
+export const EllipsisText = createComponent('span')({
+  displayName: 'EllipsisText',
+  Component(elemProps = {}, ref, Element) {
+    return <StyledEllipsisComponent as={Element} ref={ref} {...elemProps} />;
+  },
+});

package/common/lib/InputProvider.tsx

@@ -1,6 +1,4 @@
 import * as React from 'react';
-// @ts-ignore
-import elementClosestPolyfill from 'element-closest';
 
 export interface InputProviderProps {
   provideIntent?: boolean;
@@ -117,7 +115,7 @@ const supportsPassive = () => {
 /**
  * This component takes heavy inspiration from what-input (https://github.com/ten1seven/what-input)
  */
-export class InputProvider extends React.Component<InputProviderProps> {
+export class InputProvider extends React.Component<React.PropsWithChildren<InputProviderProps>> {
   private eventTimer: number | undefined;
 
   private currentInput: InputType;
@@ -171,9 +169,6 @@ export class InputProvider extends React.Component<InputProviderProps> {
   }
 
   componentDidMount() {
-    // For IE11 and under, we'll need to polyfill element.closest
-    elementClosestPolyfill(window);
-
     // Check for passive event listener support
     this.supportsPassive = supportsPassive();
 

package/common/lib/responsive/useResponsiveContainerStyles.ts

@@ -0,0 +1,128 @@
+import { useTheme, breakpointKeys, CanvasBreakpoints } from "@workday/canvas-kit-react/common";
+import type {AllStyleProps} from "@workday/canvas-kit-react/layout";
+import {isWithinBreakpoint} from '../utils/isWithinBreakpoint'
+
+export type BreakpointKeys = typeof breakpointKeys[number];
+
+type ResponsiveCSSObject<T> = {
+  [P in keyof T]: Partial<Record<BreakpointKeys, AllStyleProps>> &
+    AllStyleProps;
+};
+type CSSObject<T> = {
+  [P in keyof T]: AllStyleProps;
+};
+
+// Takes in CanvasBreakpoint keys and returns current breakpoint key. Current breakpoint key is determined by the `width` of the container
+
+const getSize = (width: number, breakpoints: CanvasBreakpoints) => {
+  const ranges: {[key: string ]: [number, number?]} = {
+    'zero': [0, breakpoints.s],
+    's': [breakpoints.s, breakpoints.m],
+    'm': [breakpoints.m, breakpoints.l],
+    'l': [breakpoints.l, breakpoints.xl],
+    'xl': [breakpoints.xl]
+  };
+  return breakpointKeys.find((size: BreakpointKeys) => isWithinBreakpoint(width, ...ranges[size])) || 'zero';
+}
+
+// Returns responsive style objects that are within the current CanvasBreakpoint size
+
+function getStyles<T>(key: BreakpointKeys, styles: ResponsiveCSSObject<T>) {
+  const responsiveStyles = {} as CSSObject<T>;
+  const breakpointSize = breakpointKeys.indexOf(key);
+  for (let i = 0; i <= breakpointSize; i++) {
+    const breakpointName = breakpointKeys[i];
+    // property is key of the style object
+    Object.keys(styles).forEach((property) => {
+      const { zero, s, m, l, xl, ...base } = styles[property as keyof T];
+      const currentBreakpointStyles =
+        styles[property as keyof T][breakpointName] ?? {};
+      const previousBreakpointStyles = responsiveStyles[property as keyof T] ?? {};
+      responsiveStyles[property as keyof T] = {
+        ...base,
+        ...previousBreakpointStyles,
+        ...currentBreakpointStyles
+      };
+    });
+  }
+  return responsiveStyles;
+}
+
+/**
+ * useResponsiveContainerStyles
+ *
+ * ---
+ *
+ * This hook allows you to create container-based responsive styles with objects.
+ * It accepts two or three arguments: the responsive style object, the container width, and (optionally) the theme object.
+ * Each style object accepts five breakpoint keys: "zero", "s", "m", "l", and "xl".
+ * The sizes will act like `min-width`. For example, if you want to apply styles from `medium` and up, then you would write those styles under `m`.
+ *
+ * @example
+ * ```tsx
+import {Flex, Box} from '@workday/canvas-kit-react/layout';
+import {
+  useResponsiveStyles,
+} from '@workday/canvas-kit-react/common';
+
+const ref = React.useRef(null);
+const [containerWidth, setContainerWidth] = React.useState(0);
+
+useResizeObserver({
+  ref: ref,
+  onResize: data => {
+    setWidth(data.width || 0);
+  },
+});
+
+const containerResponsiveStyles = useResponsiveStyles(
+  {
+    flex: {
+      flexDirection: 'column',
+      padding: 'm',
+      depth: 1,
+      borderRadius: 'l',
+      zero: {
+        backgroundColor: 'Red',
+      },
+      s: {
+        backgroundColor: 'Orange',
+      },
+      m: {
+        backgroundColor: 'Yellow',
+      },
+      l: {
+        backgroundColor: 'Green',
+      },
+      xl: {
+        backgroundColor: 'Blue',
+      },
+    },
+    box: {
+      padding: 's',
+    },
+  },
+  containerWidth
+);
+
+return (
+    <Box ref={ref}>
+      <Flex {...containerResponsiveStyles.flex}>
+        <Box {...containerResponsiveStyles.box}>Hello World</Box>
+      </Flex>
+    </Box>
+);
+```
+ */
+
+export function useResponsiveContainerStyles<T extends ResponsiveCSSObject<T>>(
+  styles: ResponsiveCSSObject<T>,
+  width: number,
+  theme = {}
+) {
+  const canvasTheme = useTheme(theme);
+  const breakpoints = canvasTheme.canvas.breakpoints.values;
+
+  const size = getSize(width, breakpoints);
+  return getStyles(size, styles);
+}

package/common/lib/styles/focusRing.ts

@@ -1,7 +1,6 @@
 import {keyframes, Theme, CSSObject} from '@emotion/react';
-import canvas from '@workday/canvas-kit-react/tokens';
+import {canvas} from '@workday/canvas-kit-react/tokens';
 import {defaultCanvasTheme} from '../theming/index';
-import memoize from 'lodash/memoize';
 
 interface FocusRingOptions {
   width?: number;
@@ -16,7 +15,6 @@ interface FocusRingOptions {
   inset?: 'inner' | 'outer';
   innerColor?: string;
   outerColor?: string;
-  memoize?: boolean;
 }
 
 function calculateFocusRing({
@@ -62,8 +60,6 @@ function calculateFocusRing({
   return {boxShadow};
 }
 
-export const memoizedFocusRing = memoize(calculateFocusRing, (...args) => JSON.stringify(args));
-
 /**
  * A utility to create a canvas style focus ring around your widget.
  * By default, this mixin will create a 2px focus ring tightly wrapped
@@ -96,7 +92,6 @@ export function focusRing(options: FocusRingOptions = {}, theme?: Theme): CSSObj
     outerColor = theme && theme.canvas
       ? theme.canvas.palette.common.focusOutline
       : defaultCanvasTheme.palette.common.focusOutline,
-    memoize = true,
     inset,
   } = options;
 
@@ -109,9 +104,5 @@ export function focusRing(options: FocusRingOptions = {}, theme?: Theme): CSSObj
     inset,
   };
 
-  if (memoize) {
-    return memoizedFocusRing(args);
-  }
-
   return calculateFocusRing(args);
 }

package/common/lib/theming/README.md

@@ -241,6 +241,103 @@ window.workday = {
 If the theme is not available via a context, Canvas Kit components will attempt to pull it from this
 variable before falling back to the default theme.
 
+## Accessing the theme value
+
+Canvas Kit provides two functions to access the current theme, `getTheme` and `useTheme`. If you
+need to access the theme within a function component, use the hook, `useTheme`. If you need to
+access the theme within a `styled` component, a class component, or outside a component, use
+`getTheme`. The main difference is `useTheme` is intended to work within the `CanvasProvider` and
+will check the `ThemeContext` for the theme first. Both functions check the window for the theme and
+fall back to the default theme is nothing is found. Both functions will return a full theme object
+in this shape:
+
+**Return value**
+
+```tsx
+{
+  canvas: {
+    palette: {
+      // ...
+    },
+    breakpoints: {
+      // ...
+    },
+    direction: ContentDirection.LTR,
+  },
+  // other themes can be placed here
+}
+```
+
+### getTheme
+
+`getTheme` is a function that returns the full theme object with the Canvas Kit theme under the
+`canvas` key. It should be used with `styled` components, class components, or outside components.
+
+Below is an example of how to use `getTheme` to build responsive media query styles with the
+breakpoint functions provided in the theme.
+
+```tsx
+import {getTheme} from '@workday/canvas-kit-react/common';
+
+const theme = getTheme();
+const {up, down} = theme.canvas.breakpoints;
+const small = down('m'); // Returns '@media (max-width: 768px)'
+const medium = up('m'); // Returns '@media (min-width: 768px)'
+const styles = {
+  [small]: {
+    margin: space.m,
+  },
+  [medium]: {
+    margin: space.l,
+  },
+};
+```
+
+### useTheme
+
+`useTheme` is hook to get the full theme object. It should be used only with functional compoents
+wrapped in ContextProvider. Function returns a theme object with the Canvas Kit theme under the
+canvas key.
+
+`useTheme` should be used only inside functional component otherwise it will show a warning if the
+theme context value has not been found. In that case you will need to use `getTheme`.
+
+Below is an example showing how to use `useTheme` in a function component to set `Subtext`'s color
+to the error color provided by the theme.
+
+```tsx
+export const ErrorMessage = () => {
+  const theme = useTheme();
+  return (
+    <Subtext size="large" color={theme.canvas.palette.error.main}>
+  )
+}
+```
+
+### Overwriting the theme
+
+You can also use both functions to overwrite the theme object by providing a partial or full theme
+object to overwrite the current theme. In the example below, we're setting a custom content
+direction, which can be passed to either `useTheme` or `getTheme`. These functions will properly
+merge your the partial theme with the default Canvas theme and return a complete theme object.
+
+```tsx
+import {ContentDirection, useTheme, getTheme} from '@workday/canvas-kit-react/common';
+
+const customTheme = {
+  canvas: {
+    // set the content direction to right-to-left
+    direction: ContentDirection.RTL,
+  },
+};
+
+// Overwriting the theme with useTheme
+const customTheme = useTheme(customTheme);
+
+// Overwriting the theme with getTheme
+const customTheme = getTheme(customTheme);
+```
+
 ## Breakpoints
 
 Breakpoints are used by media queries to conditionally apply or modify styles based on the viewport

package/common/lib/theming/createCanvasTheme.ts

@@ -1,7 +1,4 @@
 import chroma from 'chroma-js';
-import merge from 'lodash/merge';
-import memoize from 'lodash/memoize';
-import findKey from 'lodash/findKey';
 import colors from '@workday/canvas-colors-web';
 import {defaultCanvasTheme} from './theme';
 import {
@@ -14,40 +11,43 @@ import {
 import {CanvasColor} from '@workday/canvas-kit-react/tokens';
 import {pickForegroundColor} from '../utils';
 
-export enum ColorDirection {
-  Darken,
-  Brighten,
-}
-
-export function shiftColor(hexColor: string, direction: ColorDirection) {
-  const canvasColor = findKey(colors, color => color === hexColor);
+// Should these be exported?
+import {deepMerge} from '../utils/deepMerge';
+import {memoize} from '../utils/memoize';
 
-  const darken = direction === ColorDirection.Darken;
+export const shiftColor = memoize(
+  (hexColor: string, amount = 100) => {
+    const canvasColor = Object.keys(colors).find(color => colors[color] === hexColor);
 
-  if (canvasColor) {
-    const colorRegex = /([a-zAz]*)(\d{3})/g;
-    const match = colorRegex.exec(canvasColor);
+    if (canvasColor) {
+      const colorRegex = /([a-zAz]*)(\d{3})/g;
+      const match = colorRegex.exec(canvasColor);
 
-    if (match) {
-      const baseColor = match[1];
-      const shadeNumber = parseInt(match[2], 10);
+      if (match) {
+        const baseColor = match[1];
+        const shadeNumber = parseInt(match[2], 10);
 
-      const newShade = darken ? shadeNumber + 100 : shadeNumber - 100;
+        const newShade = shadeNumber + amount;
 
-      if (newShade >= 100 && newShade <= 600) {
-        return colors[(baseColor + newShade) as CanvasColor];
+        if (newShade >= 100 && newShade <= 600) {
+          return colors[(baseColor + newShade) as CanvasColor];
+        }
       }
     }
-  }
 
-  try {
-    const newColor = darken ? chroma(hexColor).darken() : chroma(hexColor).brighten();
-    return newColor.hex();
-  } catch (e) {
-    console.warn(`Invalid color '${hexColor}' used in theme`);
-    return hexColor;
-  }
-}
+    try {
+      const newColor =
+        amount > 0
+          ? chroma(hexColor).darken(amount / 100)
+          : chroma(hexColor).brighten(-amount / 100);
+      return newColor.hex();
+    } catch (e) {
+      console.warn(`Invalid color '${hexColor}' used in theme`);
+      return hexColor;
+    }
+  },
+  (color, value) => `${color}.${value}`
+);
 
 function fillPalette(
   defaultPalette: CanvasThemePalette,
@@ -59,21 +59,13 @@ function fillPalette(
 
   const main = palette.main || defaultPalette.main;
   const dark =
-    palette.dark ||
-    (palette.main && shiftColor(palette.main, ColorDirection.Darken)) ||
-    defaultPalette.dark;
+    palette.dark || (palette.main && shiftColor(palette.main, 100)) || defaultPalette.dark;
   const darkest =
-    palette.darkest ||
-    (palette.main && shiftColor(dark, ColorDirection.Darken)) ||
-    defaultPalette.darkest;
+    palette.darkest || (palette.main && shiftColor(palette.main, 200)) || defaultPalette.darkest;
   const light =
-    palette.light ||
-    (palette.main && shiftColor(palette.main, ColorDirection.Brighten)) ||
-    defaultPalette.light;
+    palette.light || (palette.main && shiftColor(palette.main, -100)) || defaultPalette.light;
   const lightest =
-    palette.lightest ||
-    (palette.main && shiftColor(light, ColorDirection.Brighten)) ||
-    defaultPalette.lightest;
+    palette.lightest || (palette.main && shiftColor(palette.main, -200)) || defaultPalette.lightest;
   const contrast = palette.contrast || pickForegroundColor(main) || defaultPalette.contrast;
 
   return {
@@ -103,7 +95,12 @@ function calculateCanvasTheme(partialTheme: PartialCanvasTheme): CanvasTheme {
     direction: direction === ContentDirection.RTL ? direction : ContentDirection.LTR,
   };
 
-  return merge({}, defaultCanvasTheme, mergeable, extraFields) as CanvasTheme;
+  return deepMerge(deepMerge({}, defaultCanvasTheme), {...mergeable, ...extraFields});
 }
 
+/**
+ * Creates a full {@link CanvasTheme} from any partial theme by deeply merging with the
+ * `defaultCanvasTheme` object. The function is memoized, but it is best to run this function
+ * only once and save the result.
+ */
 export const createCanvasTheme = memoize(calculateCanvasTheme, (...args) => JSON.stringify(args));

package/common/lib/theming/getObjectProxy.ts

@@ -0,0 +1,37 @@
+/**
+ * For custom themes that do not overwrite every default.
+ */
+export type RecursivePartial<T> = {
+  [P in keyof T]?: RecursivePartial<T[P]>;
+};
+
+/**
+ * The functions gets a new object proxy. This is used for theme to ensure regardless of a partial theme object
+ * there will be a fallback theme object so that properties aren't undefined regardless of the `target` object.
+ * This function will also handle nested properties.
+ * @param target A partial object with up to the same shape as the `fallback` object
+ * @param fallback A fallback object. If a property to be accessed from the proxy is not available on the target object, the fallback object will be used
+ */
+export function getObjectProxy<T extends {}>(
+  target: RecursivePartial<T> | undefined,
+  fallback: T
+): T {
+  if (target) {
+    return new Proxy(target, {
+      get<T>(target: T, prop: string | symbol, receiver: any) {
+        if (typeof (fallback as any)[prop] === 'object') {
+          return getObjectProxy(target[prop as keyof T], (fallback as any)[prop]);
+        }
+        const targetProp = target[prop as keyof T];
+        if (targetProp !== undefined) {
+          return targetProp;
+        }
+        return Reflect.get(fallback, prop, receiver);
+      },
+      ownKeys() {
+        return Reflect.ownKeys(fallback);
+      },
+    }) as T;
+  }
+  return fallback;
+}

package/common/lib/theming/index.ts

@@ -1,7 +1,9 @@
 export * from './breakpoints';
 export {createCanvasTheme} from './createCanvasTheme';
 export * from './types';
-export {default as styled} from './styled';
+export {default as styled, StyleRewriteFn} from './styled';
 export * from './theme';
 export * from './useTheme';
+export * from './useThemedRing';
 export * from './useIsRTL';
+export * from './getObjectProxy';

package/common/lib/theming/styled.ts

@@ -1,22 +1,25 @@
 import {default as emotionStyled, CreateStyled, Interpolation, CSSObject} from '@emotion/styled';
+import {CSSProperties} from '@workday/canvas-kit-react/tokens';
 
 import {useTheme, EmotionCanvasTheme, ContentDirection} from './index';
 import rtlCSSJS from 'rtl-css-js';
-import {convertToStaticStates} from '../utils/StaticStates';
 
 const noop = (styles: any) => styles;
 
 // Pulled from https://github.com/emotion-js/emotion/blob/master/packages/styled-base/src/utils.js#L6 (not exported)
 type Interpolations = Array<any>;
+export type StyleRewriteFn = (obj?: CSSProperties) => CSSProperties | undefined;
 
 function styled<Props>(node: any) {
   return (...args: Interpolation<Props>[]) => {
     const newArgs: Interpolations = args.map(
-      interpolation => (props: Props & {theme: EmotionCanvasTheme & {_staticStates?: boolean}}) => {
+      interpolation => (
+        props: Props & {theme: EmotionCanvasTheme & {_styleRewriteFn?: StyleRewriteFn}}
+      ) => {
         props.theme = useTheme(props.theme);
         const direction = props.theme.canvas.direction;
         const maybeFlip = direction === ContentDirection.RTL ? rtlCSSJS : noop;
-        const maybeConvert = props.theme._staticStates ? convertToStaticStates : noop;
+        const maybeConvert = props.theme._styleRewriteFn || noop;
         try {
           if (typeof interpolation === 'function') {
             return maybeFlip(maybeConvert(interpolation(props)) as CSSObject);

package/common/lib/theming/useTheme.ts

@@ -1,4 +1,6 @@
-import get from 'lodash/get';
+// refactor for v5
+/// <reference types="@types/node" />
+
 import {useTheme as useEmotionTheme} from '@emotion/react';
 import {
   defaultCanvasTheme,
@@ -13,12 +15,61 @@ const getFilledTheme = (theme: PartialEmotionCanvasTheme) => ({
 });
 
 /**
- * Hook function to get the correct theme object.
- * @param {Object=} theme - The theme object returned from the emotion ThemeContext
- * (through ThemeProvider). The Canvas Kit theme is namespaced within this variable under the `canvas` key.
+ * Function to get the correct theme object for `styled` and class components
+ * or to be used outside component.
+ * @param {Object=} theme - The theme object with the Canvas Kit theme.
+ * It should be namespaced within this variable under the `canvas` key.
+ * Value of `canvas` property is any partial or full theme object to overwtite default theme.
+ *
+ * @returns An object containing updated or default Canvas Kit theme under `canvas` key.
+ *
+ * The passed partial theme object will be merged with the default Canvas theme
+ * (using memoized createCanvasTheme()) to establish any missing fields that have
+ * not been defined by the consumer's theme object.
+ *
+ * If theme is not passed, the function will try to retrieve it from the window object.
+ * If window theme is not found, it will return the default Canvas theme.
+ *
+ * @example
+ * import {getTheme} from '@workday/canvas-kit-react/common';
+ *
+ * const theme = getTheme();
+ * const {up, down} = theme.canvas.breakpoints;
+ * const small = down('m'); // Returns '@media (max-width: 768px)'
+ * const medium = up('m'); // Returns '@media (min-width: 768px)'
+ *
+ * const styles = {
+ *  [small]: {
+ *    margin: space.m
+ *  },
+ *  [medium]: {
+ *    margin: space.l
+ *  }
+ * }
+ */
+export function getTheme(theme?: PartialEmotionCanvasTheme): EmotionCanvasTheme {
+  if (theme?.canvas) {
+    return getFilledTheme(theme);
+  }
+
+  const windowTheme = typeof window !== 'undefined' && (window as any)?.workday?.canvas?.theme;
+
+  if (windowTheme) {
+    return getFilledTheme({canvas: windowTheme});
+  }
+
+  return {canvas: defaultCanvasTheme};
+}
+
+/**
+ * Hook function to get the correct theme object for functional components.
+ * @param {Object=} theme - The theme object with the Canvas Kit theme.
+ * It should be namespaced within this variable under the `canvas` key.
+ * Value of `canvas` property is any partial or full theme object to overwtite default theme.
  *
- * NOTE: If you are using a class component, you MUST pass the theme.
- * If not passed, the function will try to pull the theme from ThemeContext.
+ * @returns An object containing updated or default Canvas Kit theme under `canvas` key.
+ *
+ * NOTE: If theme is not passed, the function will try to pull the theme from ThemeContext.
  * If that does not work, it will try to retrieve it from the window object.
  * As a last resort, it will return the default Canvas theme.
  *
@@ -29,26 +80,31 @@ const getFilledTheme = (theme: PartialEmotionCanvasTheme) => ({
  * Providing the default theme here is currently a work around for when no
  * ThemeProvider or context exists.
  * Tracked on https://github.com/emotion-js/emotion/issues/1193.
+ *
+ * @example
+ * export const ErrorMessage = () => {
+ *  const theme = useTheme();
+ *  return (
+ *    <Subtext size="large" color={theme.canvas.palette.error.main}>
+ *  );
+ * }
  */
 export function useTheme(theme?: PartialEmotionCanvasTheme): EmotionCanvasTheme {
-  if (theme && theme.canvas) {
-    return getFilledTheme(theme);
-  }
-
-  try {
-    // eslint-disable-next-line react-hooks/rules-of-hooks
-    const contextTheme = useEmotionTheme() as EmotionCanvasTheme;
-    if (contextTheme && contextTheme.canvas) {
-      return getFilledTheme(contextTheme);
+  if (!theme) {
+    try {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const contextTheme = useEmotionTheme() as EmotionCanvasTheme;
+      if (contextTheme?.canvas) {
+        return getFilledTheme(contextTheme);
+      }
+    } catch (e) {
+      if (process && process.env.NODE_ENV === 'development') {
+        console.warn(
+          'useTheme: Context not supported or invalid. Please consider using `getTheme` function instead for `styled` or class components.'
+        );
+      }
     }
-  } catch (e) {
-    // Context not supported or invalid (probably called from within a class component)
-  }
-
-  const windowTheme = typeof window !== 'undefined' && get(window, 'window.workday.canvas.theme');
-  if (windowTheme) {
-    return getFilledTheme({canvas: windowTheme});
   }
 
-  return {canvas: defaultCanvasTheme};
+  return getTheme(theme);
 }