@workday/canvas-kit-react 5.3.17 → 5.4.0-next.1

package/button/lib/parts/ButtonLabelIcon.tsx

@@ -5,22 +5,25 @@ import isPropValid from '@emotion/is-prop-valid';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
 import {styled} from '@workday/canvas-kit-react/common';
 
+import {ButtonSizes, IconPositions} from '../types';
 export interface ButtonLabelIconProps {
   /**
-   * The size of the Button.
+   * There are four button sizes: `extraSmall`, `small`, `medium`, and `large`.
+   *
    * @default 'medium'
    */
-  size?: 'small' | 'medium' | 'large';
+  size?: ButtonSizes;
   /**
    * The icon of the Button.
    * Note: not displayed at `small` size
    */
   icon?: CanvasSystemIcon;
   /**
-   * The position of the TertiaryButton icon.
+   * Button icon positions can either be `left` or `right`.
+   * If no value is provided, it defaults to `left`.
    * @default 'left'
    */
-  iconPosition?: 'left' | 'right';
+  iconPosition?: IconPositions;
   /**
    * If set to `true`, transform the icon's x-axis to mirror the graphic
    * @default false
@@ -28,8 +31,29 @@ export interface ButtonLabelIconProps {
   shouldMirrorIcon?: boolean;
 }
 
-const ICON_SIZE = 24;
-const SMALL_ICON_SIZE = 20;
+const iconSizes: Record<ButtonSizes, number> = {
+  extraSmall: 18,
+  small: 20,
+  medium: 20,
+  large: 24,
+};
+
+const getIconPositionStyles = ({iconPosition, size}: ButtonLabelIconProps) => {
+  // Adjust margin values for visual balance, large buttons require 8px
+  const balancingMargin = size === 'large' ? space.xxs : space.xxxs;
+  // iconPosition can only be "right", "left", or undefined (defaults to "left")
+  if (iconPosition === 'right') {
+    return {
+      marginLeft: undefined,
+      marginRight: `-${balancingMargin} !important`,
+    };
+  } else {
+    return {
+      marginLeft: `-${balancingMargin} !important`,
+      marginRight: undefined,
+    };
+  }
+};
 
 const ButtonLabelIconStyled = styled('span', {
   shouldForwardProp: prop => isPropValid(prop) && prop !== 'size',
@@ -38,13 +62,10 @@ const ButtonLabelIconStyled = styled('span', {
     display: 'inline-block',
   },
   ({size}) => ({
-    width: size === 'small' ? SMALL_ICON_SIZE : ICON_SIZE,
-    height: size === 'small' ? SMALL_ICON_SIZE : ICON_SIZE,
+    width: size ? iconSizes[size] : iconSizes.medium,
+    height: size ? iconSizes[size] : iconSizes.medium,
   }),
-  ({iconPosition}) => ({
-    marginLeft: iconPosition === 'right' ? undefined : `-${space.xxxs} !important`,
-    marginRight: iconPosition === 'right' ? `-${space.xxxs} !important` : undefined,
-  })
+  getIconPositionStyles
 );
 
 export const ButtonLabelIcon = ({
@@ -54,12 +75,11 @@ export const ButtonLabelIcon = ({
   shouldMirrorIcon = false,
   ...elemProps
 }: ButtonLabelIconProps) => {
-  /* istanbul ignore next line for coverage */
   if (icon === undefined) {
     return null;
   }
 
-  const iconSize = size === 'small' ? SMALL_ICON_SIZE : undefined;
+  const iconSize = size ? iconSizes[size] : undefined;
 
   return (
     <ButtonLabelIconStyled iconPosition={iconPosition} size={size} {...elemProps}>

package/button/lib/types.ts

@@ -20,3 +20,14 @@ export interface ButtonColors {
   };
   disabled: ButtonStateColors;
 }
+
+/**
+ * There are four button sizes: `extraSmall`, `small`, `medium`, and `large`.
+ * If no size is provided, it will default to `medium`.
+ *
+ * @default 'medium'
+ */
+export type ButtonSizes = 'extraSmall' | 'small' | 'medium' | 'large';
+// TODO: Remove TertiaryButtonSizes in favor of button sizes when we add Tertiary large
+export type TertiaryButtonSizes = 'extraSmall' | 'small' | 'medium';
+export type IconPositions = 'left' | 'right';

package/checkbox/lib/Checkbox.tsx

@@ -33,7 +33,7 @@ export interface CheckboxProps extends Themeable {
   disabled?: boolean;
   /**
    * The HTML `id` of the underlying checkbox input element. This is required if `label` is defined as a non-empty string.
-   * @default A uniquely generated id by uuid()
+   * @default A uniquely generated id
    */
   id?: string;
   /**

package/common/README.md

@@ -17,6 +17,9 @@ Includes:
 - [Component Functions](#component-functions)
   - [createComponent](#createcomponent)
   - [ExtractProps](#extractprops)
+- [Common Hooks](#common-hooks)
+  - [useUniqueId](#useuniqueid)
+- [Utility Functions](#utility-functions)
 
 ## CanvasProvider
 
@@ -369,3 +372,78 @@ const MyNewComponent = createComponent('aside')(
 
 If the component is a `Component` and not an `ElementComponent`, only the prop interface will ever
 be returned since there is not HTML attribute interface associated with `Component`.
+
+## Common Hooks
+
+### useUniqueId
+
+A hook to generate a unique identifier for an element. Most commonly used for accessibility. The
+hook will generate a unique id the first render and always return the same id every render. This
+uses [generateUniqueId](#generateuniqueid) internally.
+
+```tsx
+const MyComponent = () => {
+  const id = useUniqueId();
+
+  return <div id={id}>Hello!</div>;
+};
+```
+
+If you wish to support user-defined ids, `useUniqueId` allows an optional id to override. This
+provides a safe and easy way of handling id overrides without conditional hooks.
+
+```tsx
+const MyComponent = ({id}) => {
+  const localId = useUniqueId(id);
+
+  return <div id={localId}>Hello!</div>;
+};
+```
+
+## Utility Functions
+
+### generateUniqueId
+
+Generates a unique and HTML5 compliant identifier every time it is called. Internally it uses a 4
+character random seed starting with a letter. This seed is unique to each instance of this package
+meaning different versions of Canvas Kit on the page will have a different seed. Each call will use
+a Base 36 string (10 numbers + 26 letters) based on an incremented number. The incremented number
+always starts at 0 and can be reset for testing purposes using
+[resetUniqueIdCount](#resetuniqueidcount). [setUniqueSeed](#setuniqueseed) can also be used for
+testing or server side rendering to get the same results during hydration.
+
+```ts
+const id1 = generateUniqueId(); // vi1e0
+const id2 = generateUniqueId(); // vi1e1
+```
+
+### setUniqueSeed
+
+Update the seed used by the id generator. This is useful for snapshot tests to help stabilize ids
+generated each run. This could also be used for server-side hydration - if you choose the same seed
+for server and set that on the client before components are rendered, the ids generated will be the
+same.
+
+For snapshot testing, this will help stabilize snapshot tests. Use in conjunction with
+[resetUniqueIdCount](#resetuniqueidcount).
+
+```ts
+// set in a script tag from the server
+setUniqueSeed(window.__ID_SEED); // set in a script tag from the server
+
+// jest setup
+before(() => {
+  setUniqueSeed('a');
+});
+```
+
+### resetUniqueIdCount
+
+This should only be called for tests in `beforeEach` for snapshot tests. Use in conjunction with
+[setUniqueSeed](#setuniqueseed).
+
+```ts
+beforeEach(() => {
+  resetUniqueIdCount();
+});
+```

package/common/index.ts

@@ -6,3 +6,4 @@ export * from './lib/styles';
 export * from './lib/utils';
 export * from './lib/CanvasProvider';
 export * from './lib/InputProvider';
+export * from './lib/EllipsisText';

package/common/lib/EllipsisText.tsx

@@ -0,0 +1,11 @@
+import styled, {CSSObject} from '@emotion/styled';
+import {ElementComponent} from '..';
+
+export const ellipsisStyles: CSSObject = {
+  whiteSpace: 'nowrap',
+  textOverflow: 'ellipsis',
+  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', {}>;

package/common/lib/parts/_brand-assets.ts

@@ -1,11 +1,11 @@
-const CDN_URI = '//design.workday.com/images/';
+const CDN_URI = 'https://design.workday.com/images/';
 
-export const dubLogoBlue = `<img src="${CDN_URI}ck-dub-logo-blue.svg">`;
+export const dubLogoBlue = `<img src="${CDN_URI}ck-dub-logo-blue.svg" alt="">`;
 
-export const dubLogoWhite = `<img src="${CDN_URI}ck-dub-logo-white.svg">`;
+export const dubLogoWhite = `<img src="${CDN_URI}ck-dub-logo-white.svg" alt="">`;
 
-export const wdayLogoBlue = `<img src="${CDN_URI}ck-wday-logo-blue.svg">`;
+export const wdayLogoBlue = `<img src="${CDN_URI}ck-wday-logo-blue.svg" alt="">`;
 
-export const wdayLogoWhite = `<img src="${CDN_URI}ck-wday-logo-white.svg">`;
+export const wdayLogoWhite = `<img src="${CDN_URI}ck-wday-logo-white.svg" alt="">`;
 
-export const miniWdayLogoBlue = `<img src="${CDN_URI}ck-mini-wday-logo-blue.svg">`;
+export const miniWdayLogoBlue = `<img src="${CDN_URI}ck-mini-wday-logo-blue.svg" alt="">`;

package/common/lib/styles/accessibleHide.ts

@@ -1,10 +1,10 @@
-import {CSSObject} from '@emotion/core';
+import {CSSProperties} from '@workday/canvas-kit-react/tokens';
 
 /**
  * A utility to hide content normal users while still making accessible to screenreaders
  * See https://a11y-101.com/development/skip-link
  */
-export const accessibleHide: CSSObject = {
+export const accessibleHide: CSSProperties = {
   clip: 'rect(1px, 1px, 1px, 1px)', // Deprecated but still used by most browsers, clip-path will be taking its place soon.
   clipPath: 'polygon(0px 0px, 0px 0px, 0px 0px, 0px 0px)',
   position: 'absolute',

package/common/lib/theming/README.md

@@ -90,10 +90,10 @@ export const defaultCanvasTheme: CanvasTheme = {
   breakpoints: {
     values: {
       zero: 0,
-      s: 600,
-      m: 960,
-      l: 1280,
-      xl: 1920,
+      s: 320,
+      m: 768,
+      l: 1024,
+      xl: 1440,
     },
     up,
     down,
@@ -243,41 +243,205 @@ variable before falling back to the default theme.
 
 ## Breakpoints
 
-Our breakpoint system is customized within the theme object. `theme.breakpoints.values` contains the
-various widths that our components adjust at:
+Breakpoints are used by media queries to conditionally apply or modify styles based on the viewport
+width. This allows the UI to be responsive to various screen sizes.
+
+### Values
+
+The canvas theme object provides five breakpoint values that correspond to the min-widths of our
+standard screen sizes.
 
 | Name   | Size (px) |
 | ------ | --------- |
 | `zero` | 0         |
-| `s`    | 600       |
-| `m`    | 960       |
-| `l`    | 1280      |
-| `xl`   | 1920      |
+| `s`    | 320       |
+| `m`    | 768       |
+| `l`    | 1024      |
+| `xl`   | 1440      |
+
+And these are our standard screen size ranges:
+
+- `small` (320px - 767px) Used for mobile-sized screens
+- `medium` (768px - 1023px) Used for tablet-sized screens
+- `large` - (1024px - 1439px) Used for laptop and small desktop screens
+- `extra-large` (≥1440px) Used for very large screens
+
+> Note: Some applications may only require a subset of screen sizes and not use all breakpoints.
+
+Our breakpoint system is customized within the theme object. `theme.canvas.breakpoints.values`.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const {theme} = useTheme();
+const {values} = theme.canvas.breakpoints;
+const styles = {
+  [`@media (min-width: ${values.m}px)`]: {
+    padding: space.s,
+  },
+};
+```
+
+### Functions
 
 There are also several functions to help with generating media queries:
 
-#### `up: (key: BreakpointFnParam) => string`
+- [Up](#Up)
+- [Down](#Down)
+- [Between](#Between)
+- [Only](#Only)
 
-> Returns a media query reflecting your specified size and up. Works with the enum (e.g.
-> BreakpointKey.m) or the string (e.g. 'm'). Example: theme.breakpoints.up(BreakpointKey.m) =>
-> '@media (min-width:960px)'
+#### Up
 
-#### `down: (key: BreakpointFnParam) => string`
+_Returns a media query above the `min-width` for the range of a given breakpoint_
 
-> Returns a media query reflecting your specified size and down. Works with the enum or the string
-> (e.g. 'm'). Example: theme.breakpoints.down(BreakpointKey.m) => '@media (max-width:1279.5px)'
+Given a `start` breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query
+(string) using a `min-width`.
 
-#### `between: (start: BreakpointFnParam, end: BreakpointFnParam) => string`
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {up} = theme.canvas.breakpoints;
+const mediaQuery = up('l'); // Returns '@media (min-width: 1024px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.m,
+  },
+};
+```
 
-> Returns a media query reflecting the sizes between your specified breakpoints. Works with the enum
-> or the string (e.g. 'm'). Example: theme.breakpoints.between(BreakpointKey.m, BreakpointKey.l) =>
-> '@media (min-width:960px) and (max-width:1919.5px)'
+#### Down
+
+_Returns a media query below the `max-width` for the range of a given breakpoint_
+
+Given an `end` breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query
+(string) using a `max-width`.
+
+> Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions. For
+> example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+
+If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of
+`0`, as seen in the second example below.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {down} = theme.canvas.breakpoints;
+const mediaQuery = down('m'); // Returns '@media (max-width: 1023.5px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.m,
+  },
+};
+```
+
+This example uses the `xl` breakpoint and only adds a `min-width` of `0` to the media query.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {down} = theme.canvas.breakpoints;
+const mediaQuery = down('xl'); // Returns '@media (min-width: 0)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.m,
+  },
+};
+```
 
-#### `only: (key: BreakpointFnParam) => string`
+#### Between
 
-> Returns a media query reflecting the size within your specified breakpoint. Works with the enum or
-> the string (e.g. 'm'). Example: theme.breakpointsonly(BreakpointKey.m) => '@media
-> (min-width:960px) and (max-width:1279.5px)'
+_Returns a media query between two given breakpoints_
+
+Given `start` and `end` breakpoint keys ("zero", "s", "m", "l", "xl"), this function returns a media
+query (string) using a min-width and max-width.
+
+> Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions. For
+> example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+
+If the `xl` breakpoint is provided, this function returns a media query with only a `min-width`, as
+seen in the second example below.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {between} = theme.canvas.breakpoints;
+// Returns '@media (min-width: 320px) and (max-width: 1023.5px)'
+const mediaQuery = between('s', 'm');
+const styles = {
+  [mediaQuery]: {
+    padding: space.s,
+  },
+};
+```
+
+This example uses `xl` as the `end` breakpoint and only adds a min-width to the media query.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {between} = theme.canvas.breakpoints;
+const mediaQuery = between('m', 'xl'); // Returns '@media (min-width: 768px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.s,
+  },
+};
+```
+
+#### Only
+
+_Returns a media query with a `min-width` and `max-width` for a given breakpoint_
+
+Given a breakpoint key ("zero", "s", "m", "l", "xl"), this function returns a media query (string)
+using a `min-width` and `max-width`.
+
+> Note: This function subtracts `0.5px` from the next breakpoint value to prevent collisions.For
+> example, `breakpoints.values.s`, has a `min-width` of `320px`, and the `max-width` is `767.5px`).
+
+If the `xl` breakpoint is provided, this function returns a media query with only a `min-width` of
+`1440px`, as seen in the second example below.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {only} = theme.canvas.breakpoints;
+const mediaQuery = only('s'); // Returns '@media (min-width: 320px) and (max-width: 767.5px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.s,
+  },
+};
+```
+
+This example uses the `xl` breakpoint and only adds a `min-width` of `1440px` to the media query.
+
+```ts
+import {useTheme} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+const theme = useTheme();
+const {only} = theme.canvas.breakpoints;
+const mediaQuery = only('m', 'xl'); // Returns '@media (min-width: 1440px)'
+const styles = {
+  [mediaQuery]: {
+    padding: space.s,
+  },
+};
+```
 
 ## useIsRTL Hook