@workday/canvas-kit-react 8.0.0-alpha.253-next.22 → 8.0.0-alpha.428-next.2

package/combobox/lib/useComboboxInputOpenWithArrowKeys.ts

@@ -0,0 +1,21 @@
+import {createElemPropsHook} from '@workday/canvas-kit-react/common';
+
+import {useComboboxModel} from './useComboboxModel';
+
+/**
+ * Opens a `Combobox` with the up/down arrow keys. This should be used only on a
+ * {@link ComboboxInput Combobox.Input}. It adds a keydown listener for the up/down arrow keys.
+ */
+export const useComboboxInputOpenWithArrowKeys = createElemPropsHook(useComboboxModel)(model => {
+  return {
+    onKeyDown(event: React.KeyboardEvent) {
+      if (
+        event.key === 'ArrowDown' ||
+        (event.key === 'ArrowUp' && model.state.visibility !== 'visible')
+      ) {
+        model.events.show(event);
+        model.events.setWidth(event.currentTarget.clientWidth);
+      }
+    },
+  };
+});

package/combobox/lib/useComboboxLoader.ts

@@ -0,0 +1,72 @@
+import React from 'react';
+
+import {useListLoader} from '@workday/canvas-kit-react/collection';
+import {useComboboxModel} from './useComboboxModel';
+
+const useDebounce = () => {
+  const debounceTimer = React.useRef(-1);
+
+  React.useEffect(() => {
+    return () => {
+      // We want to clear any timeout on unload. We disable the ESLint rule because this is actually
+      // what we want
+
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      clearTimeout(debounceTimer.current);
+    };
+  }, []);
+
+  return (fn: (...args: any[]) => any, wait: number) => {
+    clearTimeout(debounceTimer.current);
+
+    debounceTimer.current = (setTimeout(fn, wait) as any) as number; // We don't actually care what the real return type of setTimeout is. It is a number in the browser and something else in Node
+  };
+};
+
+/**
+ * Creates a `Combobox` data loader and a model. The `Combobox` loader extends the
+ * {@link useListLoader} and connects a {@link ComboboxInput Combobox.Input} to the filter of the
+ * data loader. A simple loader using
+ * [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) could look like the
+ * following:
+ *
+ * ```ts
+ * const {model, loader} = useComboboxLoader(
+ *   {
+ *     total: 0,
+ *     pageSize: 20,
+ *     async load({pageNumber, pageSize, filter}) {
+ *       // `filter` will be a `string`
+ *       return fetch(`/myUrl?filter=${filter}`)
+ *         .then(response => response.json())
+ *         .then(response => {
+ *           return {total: response.total, items: response.items};
+ *         });
+ *     },
+ *   },
+ *   useComboboxModel
+ * );
+ * ```
+ */
+export const useComboboxLoader: typeof useListLoader = (config, modelHook) => {
+  const debounce = useDebounce();
+  const list = useListLoader(
+    {
+      shouldLoad(params, state) {
+        return (
+          (config.shouldLoad ? config.shouldLoad(params, state) : true) &&
+          state.visibility !== 'hidden'
+        );
+      },
+      ...(modelHook.mergeConfig(config, {
+        onChange(event) {
+          const value = event.currentTarget.value;
+          debounce(() => list.loader.updateFilter(value), 150);
+        },
+      } as typeof useComboboxModel.TConfig) as typeof config),
+    },
+    modelHook
+  );
+
+  return list;
+};

package/combobox/lib/useComboboxModel.tsx

@@ -0,0 +1,85 @@
+import React from 'react';
+import {createModelHook, dispatchInputEvent} from '@workday/canvas-kit-react/common';
+import {useMenuModel} from '@workday/canvas-kit-react/menu';
+
+/**
+ * An input model can be used by compound components that need to work with form fields. Some form
+ * libraries use `onChange` and `value` to update a form object. Others use `onChange` and `ref` to
+ * avoid rerendering. Also autocomplete and test libraries may use the `value` `HTMLInputElement`
+ * property. We need to normalize these use cases so subcomponents can have correct data and all
+ * use-cases are supported.
+ */
+export const useInputModel = createModelHook({
+  defaultConfig: {
+    value: undefined as string | undefined,
+
+    onChange(event: React.ChangeEvent<HTMLInputElement>) {
+      return;
+    },
+  },
+})(config => {
+  const inputRef = React.createRef<HTMLInputElement>();
+
+  return {
+    onChange: config.onChange,
+    state: {value: config.value, inputRef},
+    events: {},
+  };
+});
+
+/**
+ * `ComboboxModel` extends the {@link ListModel} and the {@link InputModel}. Selecting items from
+ * the menu will dispatch an
+ * [input](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) event on the
+ * input which should work with form libraries, automation, and autofill.
+ *
+ * ```tsx
+ * const model = useComboboxModel()
+ *
+ * <Combobox model={model}>{Combobox child components}</Combobox>
+ * ```
+ */
+export const useComboboxModel = createModelHook({
+  defaultConfig: {
+    ...useInputModel.defaultConfig,
+    ...useMenuModel.defaultConfig,
+  },
+  requiredConfig: {
+    ...useInputModel.requiredConfig,
+    ...useMenuModel.requiredConfig,
+  },
+})(config => {
+  const input = useInputModel(config);
+  const menu = useMenuModel(
+    useMenuModel.mergeConfig(config, {
+      shouldVirtualize: true,
+      onSelect({id}) {
+        dispatchInputEvent(menu.state.targetRef.current, id);
+      },
+    })
+  );
+  const [width, setWidth] = React.useState(0);
+
+  const state = {
+    /**
+     * The width of the combobox input. This is used to make sure the UI renders the menu the same
+     * width as the input.
+     */
+    width,
+    ...input.state,
+    ...menu.state,
+  };
+
+  const events = {
+    ...input.events,
+    ...menu.events,
+    /**
+     * Change the width of the menu. Usually this is set to the width of the input.
+     */
+    setWidth(width: number) {
+      setWidth(width);
+    },
+  };
+
+  return {...menu, ...input, state, events};
+});

package/combobox/package.json

@@ -0,0 +1,6 @@
+{
+  "main": "../dist/commonjs/combobox",
+  "module": "../dist/es6/combobox",
+  "sideEffects": false,
+  "types": "../dist/es6/combobox"
+}

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/styles/focusRing.ts

@@ -1,7 +1,6 @@
 import {keyframes, Theme, CSSObject} from '@emotion/react';
 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

@@ -4,4 +4,6 @@ export * from './types';
 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/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);
 }