@workday/canvas-kit-react 6.8.9 → 6.9.0-next.2

package/layout/lib/Box.tsx

@@ -0,0 +1,132 @@
+import * as React from 'react';
+import styled from '@emotion/styled';
+import isPropValid from '@emotion/is-prop-valid';
+import {createComponent, StyledType, useConstant} from '@workday/canvas-kit-react/common';
+
+// style props
+import {border, BorderStyleProps} from './utils/border';
+import {color, ColorStyleProps} from './utils/color';
+import {depth, DepthStyleProps} from './utils/depth';
+import {flexItem, FlexItemStyleProps} from './utils/flexItem';
+import {layout, LayoutStyleProps} from './utils/layout';
+import {other, OtherStyleProps} from './utils/other';
+import {position, PositionStyleProps} from './utils/position';
+import {space, SpaceStyleProps} from './utils/space';
+
+export type BoxProps = BorderStyleProps &
+  ColorStyleProps &
+  DepthStyleProps &
+  FlexItemStyleProps &
+  LayoutStyleProps &
+  OtherStyleProps &
+  PositionStyleProps &
+  SpaceStyleProps & {
+    children?: React.ReactNode;
+  };
+
+const omittedProps = ['display', 'color', 'height', 'overflow', 'width', 'border', 'background'];
+
+const shouldForwardProp = (prop: string) => {
+  return isPropValid(prop) && !omittedProps.includes(prop);
+};
+
+/**
+ * A function that allows us to call Box styles on an element and reduce the amount of elements in the React Dom tree.
+ * Instead of using the `as` in a styled function, you can just call this instead to pass those props to the styled element
+ * @example
+ * import { boxStyleFn } from '@workday/canvas-kit-react/layout';
+ * const StyledHeader = styled('h1')(
+ *  boxStyleFn,
+ *  {
+ *    fontWeight: 400,
+ *  }
+ * )
+ *
+ * ....
+ *
+ * <StyledHeader color='red'>Hello World</StyledHeader>
+ */
+export const boxStyleFn = <P extends BoxProps>(props: P) => {
+  return [
+    {
+      boxSizing: 'border-box',
+    },
+    border,
+    color,
+    depth,
+    flexItem,
+    layout,
+    position,
+    space,
+  ].reduce((result, style) => {
+    // @ts-ignore
+    const temp = typeof style === 'function' ? style(props) : style;
+    // eslint-disable-next-line guard-for-in
+    for (const key in temp) {
+      // @ts-ignore
+      result[key] = temp[key];
+    }
+    return result;
+  }, {});
+};
+
+// Meant to be used with elements. The `shouldForwardProps` will remove all style props
+const StyledBoxElement = styled('div', {shouldForwardProp})<StyledType & BoxProps>(
+  {
+    boxSizing: 'border-box',
+  },
+  border,
+  color,
+  depth,
+  flexItem,
+  layout,
+  position,
+  space
+);
+
+// Meant to be used with components. There is no `shouldForwardProps` - all props will be forwarded to the component
+const StyledBoxComponent = styled('div')<StyledType & BoxProps>(
+  {
+    boxSizing: 'border-box',
+  },
+  border,
+  color,
+  depth,
+  flexItem,
+  layout,
+  other,
+  position,
+  space
+);
+
+/**
+ * `Box` is a primitive component that provides a common, ergonomic API around Canvas design tokens.
+ * It is highly flexible, and its primary purpose is to build other components.
+ *
+ * @example
+ * import { Box, BoxProps } from '@workday/canvas-kit-react/layout';
+ *
+ * interface CardProps extends BoxProps {
+ *   // card-specific props
+ * }
+ *
+ * // `Card`'s default values are set using `BoxProps`
+ * const Card = (props: CardProps) => (
+ *   <Box depth={1} padding="m" borderRadius="l" {...props}>Hello, Card!</Box>
+ * );
+ *
+ */
+export const Box = createComponent('div')({
+  displayName: 'Box',
+  Component: ({children, ...elemProps}: BoxProps, ref, Element) => {
+    const BoxComponent = useConstant(() =>
+      typeof Element === 'string' ? StyledBoxElement : StyledBoxComponent
+    );
+
+    return (
+      <BoxComponent as={Element} ref={ref} {...elemProps}>
+        {children}
+      </BoxComponent>
+    );
+  },
+});

package/layout/lib/Flex.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import styled from '@emotion/styled';
+import {createComponent, StyledType} from '@workday/canvas-kit-react/common';
+import {Box, BoxProps} from './Box';
+
+import {flex, FlexStyleProps} from './utils/flex';
+
+export type FlexProps = BoxProps & FlexStyleProps;
+
+const StyledFlex = styled(Box)<StyledType & FlexProps>(
+  {
+    display: 'flex',
+  },
+  flex
+);
+
+/**
+ * `Flex` is a low-level layout component that provides a common, ergonomic API for applying CSS flexbox styles.
+ * It is highly flexible, and can be used on its own or to build other components.
+ * `Flex` is built on top of `Box` and has access to all `BoxProps`.
+ *
+ * @example
+ * import { Flex, FlexProps } from '@workday/canvas-kit-react/layout';
+ *
+ * interface CardProps extends FlexProps {
+ *   // card-specific props
+ * }
+ *
+ * // `Card`'s default values are set using `FlexProps`
+ * const Card = (props: CardProps) => (
+ *   <Flex flexDirection="column" alignItems="flex-start" depth={1} space="m" {...props}>
+ *     <h1>Hello, Card!</h1>
+ *     <p>This card uses flexbox to set its layout.</p>
+ *   </Flex>
+ * );
+ *
+ */
+export const Flex = createComponent('div')({
+  displayName: 'Flex',
+  Component: ({children, ...elemProps}: FlexProps, ref, Element) => {
+    return (
+      <StyledFlex as={Element} ref={ref} {...elemProps}>
+        {children}
+      </StyledFlex>
+    );
+  },
+});

package/layout/lib/Stack.tsx

@@ -0,0 +1,97 @@
+import * as React from 'react';
+import styled from '@emotion/styled';
+import {createComponent, StyledType} from '@workday/canvas-kit-react/common';
+import {Box, BoxProps} from './Box';
+import {Flex, FlexProps} from './Flex';
+import {getValidChildren} from './utils/getValidChildren';
+import {stack, StackStyleProps} from './utils/stack';
+
+export type StackProps = FlexProps & StackStyleProps;
+
+const StackItem = createComponent('div')({
+  displayName: 'Stack.Item',
+  Component: ({children, ...elemProps}: BoxProps, ref, Element) => {
+    return (
+      <Box
+        as={Element}
+        ref={ref}
+        display="inline-block"
+        flex="0 0 auto"
+        minWidth={0}
+        {...elemProps}
+      >
+        {children}
+      </Box>
+    );
+  },
+});
+
+// prevent `spacing` prop from being passed through to the HTML element
+const shouldForwardProp = (prop: string) => {
+  return prop !== 'spacing';
+};
+
+const StyledStack = styled(Flex, {shouldForwardProp})<StyledType & StackProps>(stack);
+
+export const Stack = createComponent('div')({
+  displayName: 'Stack',
+  Component: ({children, shouldWrapChildren = false, ...elemProps}: StackProps, ref, Element) => {
+    const validChildren = getValidChildren(children);
+    return (
+      <StyledStack as={Element} ref={ref} flexDirection="row" {...elemProps}>
+        {shouldWrapChildren
+          ? validChildren.map((child, index) => (
+              <StackItem key={child.props.id || index}>{child}</StackItem>
+            ))
+          : validChildren}
+      </StyledStack>
+    );
+  },
+  subComponents: {
+    Item: StackItem,
+  },
+});
+
+export interface HStackProps extends StackProps {
+  /**
+   * sets the direction for the stack
+   * @default "row"
+   * */
+  flexDirection?: 'row' | 'row-reverse';
+}
+
+export const HStack = createComponent('div')({
+  displayName: 'HStack',
+  Component: ({children, ...elemProps}: HStackProps, ref, Element) => {
+    return (
+      <Stack as={Element} ref={ref} flexDirection="row" {...elemProps}>
+        {children}
+      </Stack>
+    );
+  },
+  subComponents: {
+    Item: StackItem,
+  },
+});
+
+export interface VStackProps extends StackProps {
+  /**
+   * sets the direction for the stack
+   * @default "column"
+   * */
+  flexDirection?: 'column' | 'column-reverse';
+}
+
+export const VStack = createComponent('div')({
+  displayName: 'VStack',
+  Component: ({children, ...elemProps}: VStackProps, ref, Element) => {
+    return (
+      <Stack as={Element} ref={ref} flexDirection="column" {...elemProps}>
+        {children}
+      </Stack>
+    );
+  },
+  subComponents: {
+    Item: StackItem,
+  },
+});

package/layout/lib/utils/border.ts

@@ -0,0 +1,263 @@
+import {
+  borderRadius as borderRadiusTokens,
+  CanvasBorderRadiusKeys,
+  colors as colorTokens,
+  CanvasColor,
+} from '@workday/canvas-kit-react/tokens';
+import {
+  ContentDirection,
+  PartialEmotionCanvasTheme,
+  useTheme,
+} from '@workday/canvas-kit-react/common';
+
+import {PropertyBorder} from './types';
+
+/** style props to set the border properties */
+export type BorderShorthandStyleProps = {
+  /** sets `border` property */
+  border?: string;
+  /** sets `border-top` property */
+  borderTop?: string;
+  /** sets `border-right` property (no bidirectional support) */
+  borderRight?: string;
+  /** sets `border-bottom` property */
+  borderBottom?: string;
+  /** sets `border-left` property (no bidirectional support) */
+  borderLeft?: string;
+};
+
+/** style props to set the border color properties */
+export type BorderColorStyleProps = {
+  /** sets `border-color` property */
+  borderColor?: CanvasColor | (string & {});
+  /** sets `border-top-color` property */
+  borderTopColor?: CanvasColor | (string & {});
+  /** sets `border-right-color` property (no bidirectional support) */
+  borderRightColor?: CanvasColor | (string & {});
+  /** sets `border-bottom-color` property */
+  borderBottomColor?: CanvasColor | (string & {});
+  /** sets `border-left-color` property (no bidirectional support) */
+  borderLeftColor?: CanvasColor | (string & {});
+};
+
+/** style props to set the border radius properties */
+export type BorderRadiusStyleProps = {
+  /** sets `border-radius` property */
+  borderRadius?: CanvasBorderRadiusKeys | number | (string & {});
+  /** sets `border-top-left-radius` property */
+  borderTopLeftRadius?: CanvasBorderRadiusKeys | number | (string & {});
+  /** sets `border-top-right-radius` property */
+  borderTopRightRadius?: CanvasBorderRadiusKeys | number | (string & {});
+  /** sets `border-bottom-left-radius` property */
+  borderBottomLeftRadius?: CanvasBorderRadiusKeys | number | (string & {});
+  /** sets `border-bottom-right-radius` property */
+  borderBottomRightRadius?: CanvasBorderRadiusKeys | number | (string & {});
+};
+
+/** style props to set the border style properties */
+export type BorderLineStyleProps = {
+  /** sets `border-style` property */
+  borderStyle?: PropertyBorder;
+  /** sets `border-top-style` property */
+  borderTopStyle?: PropertyBorder;
+  /** sets `border-right-style` property (no bidirectional support) */
+  borderRightStyle?: PropertyBorder;
+  /** sets `border-bottom-style` property */
+  borderBottomStyle?: PropertyBorder;
+  /** sets `border-left-style` property (no bidirectional support) */
+  borderLeftStyle?: PropertyBorder;
+};
+
+/** style props to set the border width properties */
+export type BorderWidthStyleProps = {
+  /** sets `border-width` property */
+  borderWidth?: string | number;
+  /** sets `border-top-width` property */
+  borderTopWidth?: string | number;
+  /** sets `border-right-width` property (no bidirectional support) */
+  borderRightWidth?: string | number;
+  /** sets `border-bottom-width` property */
+  borderBottomWidth?: string | number;
+  /** sets `border-left-width` property (no bidirectional support) */
+  borderLeftWidth?: string | number;
+};
+
+export type BorderLogicalStyleProps = {
+  /** sets `border-left` property (bidirectional support) */
+  borderInlineStart?: string;
+  /** sets `border-left-color` property (bidirectional support) */
+  borderInlineStartColor?: CanvasColor | (string & {});
+  /** sets `border-left-style` property (bidirectional support) */
+  borderInlineStartStyle?: PropertyBorder;
+  /** sets `border-left-width` property (bidirectional support) */
+  borderInlineStartWidth?: string | number;
+  /** sets `border-right` property (bidirectional support) */
+  borderInlineEnd?: string;
+  /** sets `border-right-color` property (bidirectional support) */
+  borderInlineEndColor?: CanvasColor | (string & {});
+  /** sets `border-right-style` property (bidirectional support) */
+  borderInlineEndStyle?: PropertyBorder;
+  /** sets `border-right-width` property (bidirectional support) */
+  borderInlineEndWidth?: string | number;
+};
+
+/** a collection style props for border properties */
+export type BorderStyleProps = BorderShorthandStyleProps &
+  BorderColorStyleProps &
+  BorderRadiusStyleProps &
+  BorderLineStyleProps &
+  BorderWidthStyleProps &
+  BorderLogicalStyleProps;
+
+// border logical prop handlers
+const borderInlineStart = (isRTL: boolean) => (isRTL ? 'borderRight' : 'borderLeft');
+const borderInlineEnd = (isRTL: boolean) => (isRTL ? 'borderLeft' : 'borderRight');
+const borderInlineStartColor = (isRTL: boolean) => (isRTL ? 'borderRightColor' : 'borderLeftColor');
+const borderInlineEndColor = (isRTL: boolean) => (isRTL ? 'borderLeftColor' : 'borderRightColor');
+const borderInlineStartStyle = (isRTL: boolean) => (isRTL ? 'borderRightStyle' : 'borderLeftStyle');
+const borderInlineEndStyle = (isRTL: boolean) => (isRTL ? 'borderLeftStyle' : 'borderRightStyle');
+const borderInlineStartWidth = (isRTL: boolean) => (isRTL ? 'borderRightWidth' : 'borderLeftWidth');
+const borderInlineEndWidth = (isRTL: boolean) => (isRTL ? 'borderLeftWidth' : 'borderRightWidth');
+
+const borderShorthandProps = {
+  border: 'border',
+  borderTop: 'borderTop',
+  borderRight: 'borderRight',
+  borderBottom: 'borderBottom',
+  borderLeft: 'borderLeft',
+  borderInlineStart,
+  borderInlineEnd,
+};
+
+const borderColors = {
+  borderColor: 'borderColor',
+  borderTopColor: 'borderTopColor',
+  borderRightColor: 'borderRightColor',
+  borderBottomColor: 'borderBottomColor',
+  borderLeftColor: 'borderLeftColor',
+  borderInlineStartColor,
+  borderInlineEndColor,
+};
+
+const borderRadii = {
+  borderRadius: 'borderRadius',
+  borderTopLeftRadius: 'borderTopLeftRadius',
+  borderTopRightRadius: 'borderTopRightRadius',
+  borderBottomLeftRadius: 'borderBottomLeftRadius',
+  borderBottomRightRadius: 'borderBottomRightRadius',
+};
+
+const borderStyles = {
+  borderStyle: 'borderStyle',
+  borderTopStyle: 'borderTopStyle',
+  borderRightStyle: 'borderRightStyle',
+  borderBottomStyle: 'borderBottomStyle',
+  borderLeftStyle: 'borderLeftStyle',
+  borderInlineStartStyle,
+  borderInlineEndStyle,
+};
+
+const borderWidths = {
+  borderWidth: 'borderWidth',
+  borderTopWidth: 'borderTopWidth',
+  borderRightWidth: 'borderRightWidth',
+  borderBottomWidth: 'borderBottomWidth',
+  borderLeftWidth: 'borderLeftWidth',
+  borderInlineStartWidth,
+  borderInlineEndWidth,
+};
+
+/**
+ * A style prop function that takes components props and returns border styles. Some props, such as borderRadius and borderColor, are connected to our design tokens.
+ * If no `BorderStyleProps` are found, it returns an empty object.
+ *
+ * @example
+ * // You'll most likely use `border` with low-level, styled components
+ * const BoxExample = () => (
+ *   <Box border={`solid 1px #333333 ${colors.blackPepper400}`}>Hello, border styles!</Box>
+ * );
+ *
+ */
+export function border<P extends BorderStyleProps & {theme?: PartialEmotionCanvasTheme}>(props: P) {
+  // border will always be used within the context of a component, but eslint doesn't know that
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const {canvas} = useTheme(props.theme);
+  const isRTL = canvas.direction === ContentDirection.RTL;
+  const styles = {};
+  for (const key in props) {
+    if (props.hasOwnProperty(key)) {
+      if (key in borderShorthandProps) {
+        const value = props[key as keyof BorderShorthandStyleProps];
+        let attr: string;
+        if (key === 'borderInlineStart') {
+          attr = borderInlineStart(isRTL);
+        } else if (key === 'borderInlineEnd') {
+          attr = borderInlineEnd(isRTL);
+        } else {
+          attr = borderShorthandProps[key as keyof BorderShorthandStyleProps];
+        }
+        // @ts-ignore TS doesn't like adding a potentially unknown key to an object, but because we own this object, it's fine.
+        styles[attr] = value;
+        continue;
+      }
+
+      if (key in borderColors) {
+        const propValue = props[key as keyof BorderColorStyleProps] as CanvasColor | string;
+        const value = colorTokens[propValue as CanvasColor] || propValue;
+        let attr: string;
+        if (key === 'borderInlineStartColor') {
+          attr = borderInlineStartColor(isRTL);
+        } else if (key === 'borderInlineEndColor') {
+          attr = borderInlineEndColor(isRTL);
+        } else {
+          attr = borderColors[key as keyof BorderColorStyleProps];
+        }
+        // @ts-ignore TS doesn't like adding a potentially unknown key to an object, but because we own this object, it's fine.
+        styles[attr] = value;
+        continue;
+      }
+
+      if (key in borderRadii) {
+        const propValue = props[key as keyof BorderRadiusStyleProps] as
+          | CanvasBorderRadiusKeys
+          | number
+          | string;
+        const value = borderRadiusTokens[propValue as CanvasBorderRadiusKeys] || propValue;
+        const attr = borderRadii[key as keyof BorderRadiusStyleProps];
+        // @ts-ignore TS doesn't like adding a potentially unknown key to an object, but because we own this object, it's fine.
+        styles[attr] = value;
+        continue;
+      }
+
+      if (key in borderStyles) {
+        const value = props[key as keyof BorderLineStyleProps];
+        let attr: string;
+        if (key === 'borderInlineStartStyle') {
+          attr = borderInlineStartStyle(isRTL);
+        } else if (key === 'borderInlineEndStyle') {
+          attr = borderInlineEndStyle(isRTL);
+        } else {
+          attr = borderStyles[key as keyof BorderLineStyleProps];
+        }
+        // @ts-ignore TS doesn't like adding a potentially unknown key to an object, but because we own this object, it's fine.
+        styles[attr] = value;
+        continue;
+      }
+
+      if (key in borderWidths) {
+        const value = props[key as keyof BorderWidthStyleProps];
+        let attr: string;
+        if (key === 'borderInlineStartWidth') {
+          attr = borderInlineStartWidth(isRTL);
+        } else if (key === 'borderInlineEndWidth') {
+          attr = borderInlineEndWidth(isRTL);
+        } else {
+          attr = borderWidths[key as keyof BorderWidthStyleProps];
+        }
+        // @ts-ignore TS doesn't like adding a potentially unknown key to an object, but because we own this object, it's fine.
+        styles[attr] = value;
+      }
+    }
+  }
+  return styles;
+}

package/layout/lib/utils/color.ts

@@ -0,0 +1,62 @@
+import {colors as colorTokens, CanvasColor} from '@workday/canvas-kit-react/tokens';
+
+export type ColorTokens = typeof colorTokens;
+
+/** style props to for color properties */
+export type ColorStyleProps = {
+  /** sets `background` property */
+  background?: CanvasColor | (string & {});
+  /** sets `background-color` property */
+  backgroundColor?: CanvasColor | (string & {});
+  /** sets `background-image` property */
+  backgroundImage?: string;
+  /** sets `color` property */
+  color?: CanvasColor | (string & {});
+};
+
+const getBackground = (value: CanvasColor | string) => ({
+  background: colorTokens[value] || value,
+});
+
+const getBackgroundColor = (value: CanvasColor | string) => ({
+  backgroundColor: colorTokens[value] || value,
+});
+
+const getBackgroundImage = (value: string) => ({
+  backgroundImage: value,
+});
+
+const getColor = (value: CanvasColor | string) => ({
+  color: colorTokens[value] || value,
+});
+
+const colorProps = {
+  background: getBackground,
+  backgroundColor: getBackgroundColor,
+  backgroundImage: getBackgroundImage,
+  color: getColor,
+};
+
+/**
+ * A style prop function that takes components props and returns color styles from canvas token values.
+ * If no `ColorStyleProps` are found, it returns an empty object.
+ *
+ * @example
+ * // You'll most likely use `color` with low-level, styled components
+ * const BoxExample = () => (
+ *   <Box backgroundColor="blueberry500" color="frenchVanilla100">Hello, colors!</Box>
+ * );
+ *
+ */
+export function color<P extends ColorStyleProps>(props: P) {
+  let styles = {};
+  for (const key in props) {
+    if (key in colorProps) {
+      const value = props[key as keyof ColorStyleProps] as CanvasColor | string;
+      const colorFn = colorProps[key as keyof ColorStyleProps];
+      const style = colorFn(value);
+      styles = {...styles, ...style};
+    }
+  }
+  return styles;
+}

package/layout/lib/utils/depth.ts

@@ -0,0 +1,37 @@
+import {depth as depthTokens} from '@workday/canvas-kit-react/tokens';
+
+export type DepthTokens = typeof depthTokens;
+export type DepthTokenKeys = keyof DepthTokens;
+export type DepthTokenValues = DepthTokens[keyof DepthTokens];
+
+/** style props to for depth styles */
+export type DepthStyleProps = {
+  /** sets depth styles (box-shadow & border) */
+  depth?: DepthTokenKeys;
+};
+
+const depthProps = {
+  depth: (token: DepthTokenKeys) => depthTokens[token],
+};
+
+/**
+ * A style prop function that takes components props and returns depth styles from canvas token values.
+ * If no `DepthStyleProps` are found, it returns an empty object.
+ *
+ * @example
+ * // You'll mostly likely use `depth` with low-level, styled components
+ * const BoxExample = () => (
+ *   <Box depth={3}>Hello, box shadows!</Box>
+ * );
+ *
+ */
+export function depth<P extends DepthStyleProps>(props: P): DepthTokenValues {
+  for (const key in props) {
+    if (key in depthProps) {
+      const token = props[key as keyof DepthStyleProps] as DepthTokenKeys;
+      const depthFn = depthProps[key as keyof DepthStyleProps];
+      return depthFn(token);
+    }
+  }
+  return {} as DepthTokenValues;
+}