@workday/canvas-kit-react 7.0.0-alpha.129-next.3 → 7.0.0-alpha.256-next.2

package/layout/lib/Box.tsx

@@ -4,27 +4,62 @@ 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';
+import {background} from './utils/background';
+import {border} from './utils/border';
+import {color} from './utils/color';
+import {depth} from './utils/depth';
+import {flexItem} from './utils/flexItem';
+import {gridItem} from './utils/gridItem';
+import {layout} from './utils/layout';
+import {other} from './utils/other';
+import {position} from './utils/position';
+import {space} from './utils/space';
+import {text} from './utils/text';
+import {CommonStyleProps} from './utils/styleProps';
 
-export type BoxProps = BorderStyleProps &
-  ColorStyleProps &
-  DepthStyleProps &
-  FlexItemStyleProps &
-  LayoutStyleProps &
-  OtherStyleProps &
-  PositionStyleProps &
-  SpaceStyleProps & {
-    children?: React.ReactNode;
-  };
+/**
+ * Box Props
+ * ---
+ * Common style props + children
+ *
+ * - background
+ * - border
+ * - color
+ * - depth
+ * - flexItem
+ * - gridItem
+ * - layout
+ * - other
+ * - position
+ * - space
+ * - text
+ */
+export type BoxProps = CommonStyleProps & {
+  children?: React.ReactNode;
+};
 
-const omittedProps = ['display', 'color', 'height', 'overflow', 'width', 'border', 'background'];
+const omittedProps = [
+  'display',
+  'color',
+  'height',
+  'overflow',
+  'width',
+  'border',
+  'background',
+  'fontSize',
+  'fontWeight',
+  'fontFamily',
+  'letterSpacing',
+  'lineHeight',
+  'textAlign',
+  'opacity',
+  'textDecoration',
+  'textOverflow',
+  'textTransform',
+  'textShadow',
+  'whiteSpace',
+  'wordBreak',
+];
 
 const shouldForwardProp = (prop: string) => {
   return isPropValid(prop) && !omittedProps.includes(prop);
@@ -34,6 +69,7 @@ const shouldForwardProp = (prop: string) => {
  * 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,
@@ -42,22 +78,27 @@ const shouldForwardProp = (prop: string) => {
  *  }
  * )
  *
- * ....
+ * ...
  *
  * <StyledHeader color='red'>Hello World</StyledHeader>
+ * ```
  */
 export const boxStyleFn = <P extends BoxProps>(props: P) => {
   return [
     {
       boxSizing: 'border-box',
     },
+    background,
     border,
     color,
     depth,
     flexItem,
+    gridItem,
     layout,
+    other,
     position,
     space,
+    text,
   ].reduce((result, style) => {
     // @ts-ignore
     const temp = typeof style === 'function' ? style(props) : style;
@@ -71,33 +112,10 @@ export const boxStyleFn = <P extends BoxProps>(props: P) => {
 };
 
 // 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
-);
+const StyledBoxElement = styled('div', {shouldForwardProp})<StyledType & BoxProps>(boxStyleFn);
 
 // 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
-);
+const StyledBoxComponent = styled('div')<StyledType & BoxProps>(boxStyleFn);
 
 /**
  * `Box` is a primitive component that provides a common, ergonomic API around Canvas design tokens.

package/layout/lib/Column.tsx

@@ -2,13 +2,21 @@ import * as React from 'react';
 import styled from '@emotion/styled';
 import isPropValid from '@emotion/is-prop-valid';
 
-export interface ColumnProps {
+/**
+ * ### Deprecated Layout Column Props
+ *
+ * As of Canvas Kit v8, Layout is being soft-deprecated.
+ * It will be hard-deprecated (completely removed) in v9. Please see the
+ * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
+ * for more information.
+ */
+export interface DeprecatedColumnProps {
   /**
-   * The children of the Column (cannot be empty).
+   * The children of the DeprecatedColumn (cannot be empty).
    */
   children?: React.ReactNode;
   /**
-   * The left and right padding of the Column (inherits from Layout prop).
+   * The left and right padding of the DeprecatedColumn (inherits from Layout prop).
    * @default 12
    */
   spacing?: number;
@@ -24,7 +32,7 @@ export interface ColumnProps {
 
 const ColumnContainer = styled('div', {
   shouldForwardProp: prop => isPropValid(prop) && prop !== 'spacing',
-})<ColumnProps>(
+})<DeprecatedColumnProps>(
   {
     '&:first-of-type': {
       paddingLeft: 0,
@@ -58,7 +66,16 @@ const ColumnContainer = styled('div', {
   }
 );
 
-export class Column extends React.Component<ColumnProps> {
+export class DeprecatedColumn extends React.Component<DeprecatedColumnProps> {
+  componentDidMount() {
+    console.warn(
+      `This component is being deprecated and will be removed in Canvas Kit V9.\n
+      For more information, please see the V8 upgrade guide:\n
+      https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page
+      `
+    );
+  }
+
   public render() {
     const {children, spacing, columns, width, ...elemProps} = this.props;
 

package/layout/lib/Flex.tsx

@@ -5,7 +5,7 @@ import {Box, BoxProps} from './Box';
 
 import {flex, FlexStyleProps} from './utils/flex';
 
-export type FlexProps = BoxProps & FlexStyleProps;
+export type FlexProps = Omit<BoxProps, 'display'> & FlexStyleProps;
 
 const StyledFlex = styled(Box)<StyledType & FlexProps>(
   {
@@ -20,6 +20,7 @@ const StyledFlex = styled(Box)<StyledType & FlexProps>(
  * `Flex` is built on top of `Box` and has access to all `BoxProps`.
  *
  * @example
+ * ```tsx
  * import { Flex, FlexProps } from '@workday/canvas-kit-react/layout';
  *
  * interface CardProps extends FlexProps {
@@ -33,7 +34,7 @@ const StyledFlex = styled(Box)<StyledType & FlexProps>(
  *     <p>This card uses flexbox to set its layout.</p>
  *   </Flex>
  * );
- *
+ * ```
  */
 export const Flex = createComponent('div')({
   displayName: 'Flex',
@@ -44,4 +45,7 @@ export const Flex = createComponent('div')({
       </StyledFlex>
     );
   },
+  subComponents: {
+    Item: Box,
+  },
 });

package/layout/lib/Grid.tsx

@@ -0,0 +1,85 @@
+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 {grid, GridStyleProps} from './utils/grid';
+
+export type GridProps = Omit<BoxProps, 'display'> & GridStyleProps;
+export type GridItemProps = BoxProps;
+
+const StyledGrid = styled(Box)<StyledType & GridProps>(
+  {
+    display: 'grid',
+  },
+  grid
+);
+
+const GridItem = createComponent('div')({
+  displayName: 'Grid.Item',
+  Component: ({children, ...elemProps}: BoxProps, ref, Element) => {
+    return (
+      <Box as={Element} ref={ref} {...elemProps}>
+        {children}
+      </Box>
+    );
+  },
+});
+
+/**
+ * `Grid` is a two-dimensional layout system for the web. It lets you lay content out in rows and columns.
+ * It is highly flexible, and can be used on its own or to build other components.
+ * `Grid` is built on top of `Box` and has access to all `BoxProps`.
+ *
+ * @example
+ * ```tsx
+ * import { Grid } from '@workday/canvas-kit-react/layout';
+ *
+ * interface CardProps extends GridProps {
+ *   // card-specific props
+ * }
+ *
+ * // `Card`'s default values are set using `GridProps`
+ * const Card = (props: CardProps) => (
+ *   <Grid gridAutoFlow="row" alignItems="start" depth={1} space="m" {...props}>
+ *     <h1>Hello, Card!</h1>
+ *     <p>This card uses grid to set its layout.</p>
+ *   </Grid>
+ * );
+ *```
+ */
+export const Grid = createComponent('div')({
+  displayName: 'Grid',
+  Component: ({children, ...elemProps}: GridProps, ref, Element) => {
+    return (
+      <StyledGrid as={Element} ref={ref} {...elemProps}>
+        {children}
+      </StyledGrid>
+    );
+  },
+  subComponents: {
+    /**
+     * `<Grid.Item />` is the child specific sub-component to `<Grid/>`. `<Grid.Item />` gets child specific props, whereas `<Grid./>` gets parent container props.
+     *
+     * @example
+     * ```
+     * import { Grid } from '@workday/canvas-kit-react/layout';
+     * `Grid` is built on top of `Box` so `<Grid.Item />` gets all `BoxProps` as well.
+     *
+     * interface CardProps extends GridItemStyleProps {
+     *   // card-specific props
+     * }
+     *
+     * // `Card`'s default values are set using `GridItemStyleProps`
+     * const Card = (props: CardProps) => (
+     *   <Grid.Item gridRowStart="1" gridArea="Card" {...props}>
+     *     <h1>Hello, Card!</h1>
+     *     <p>This card uses grid child specific props to set its layout.</p>
+     *   </Grid.Item>
+     * );
+     *```
+     */
+
+    Item: GridItem,
+  },
+});

package/layout/lib/Layout.tsx

@@ -1,26 +1,34 @@
 import * as React from 'react';
 import styled from '@emotion/styled';
 import {GenericStyle} from '@workday/canvas-kit-react/common';
-import {Column, ColumnProps} from './Column';
+import {DeprecatedColumn, DeprecatedColumnProps} from './Column';
 import {canvas, spaceNumbers} from '@workday/canvas-kit-react/tokens';
 import isPropValid from '@emotion/is-prop-valid';
 
-export interface LayoutProps {
+/**
+ * ### Deprecated Layout Props
+ *
+ * As of Canvas Kit v8, Layout is being soft-deprecated.
+ * It will be hard-deprecated (completely removed) in v9. Please see the
+ * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
+ * for more information.
+ */
+export interface DeprecatedLayoutProps {
   /**
-   * The children of the Layout (cannot be empty).
+   * The children of the DeprecatedLayout (cannot be empty).
    */
-  children: React.ReactElement<ColumnProps>[] | React.ReactNode;
+  children: React.ReactElement<DeprecatedColumnProps>[] | React.ReactNode;
   /**
-   * The spacing of the Layout children.
+   * The spacing of the DeprecatedLayout children.
    */
   spacing?: number;
   /**
-   * The padding of the Layout's outside container.
+   * The padding of the DeprecatedLayout's outside container.
    * @default 12
    */
   gutter?: number | string;
   /**
-   * If true, set the max width of the Layout container to `1280px`.
+   * If true, set the max width of the DeprecatedLayout container to `1280px`.
    * @default false
    */
   capWidth?: boolean;
@@ -37,7 +45,7 @@ const LayoutStyles: GenericStyle = {
 
 const LayoutContainer = styled('div', {
   shouldForwardProp: prop => isPropValid(prop) && prop !== 'spacing',
-})<LayoutProps>(
+})<DeprecatedLayoutProps>(
   LayoutStyles.styles,
   ({gutter}) => {
     if (gutter === 0) {
@@ -58,15 +66,32 @@ const LayoutContainer = styled('div', {
   }
 );
 
-export class Layout extends React.Component<LayoutProps> {
-  public static Column = Column;
+/**
+ * ### Deprecated Layout
+ *
+ * As of Canvas Kit v8, Layout is being soft-deprecated.
+ * It will be hard-deprecated (completely removed) in v9. Please see the
+ * [upgrade guide](https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page)
+ * for more information.
+ */
+export class DeprecatedLayout extends React.Component<DeprecatedLayoutProps> {
+  componentDidMount() {
+    console.warn(
+      `This component is being deprecated and will be removed in Canvas Kit V9.\n
+      For more information, please see the V8 upgrade guide:\n
+      https://workday.github.io/canvas-kit/?path=/story/welcome-upgrade-guides-v8-0--page
+      `
+    );
+  }
+
+  public static Column = DeprecatedColumn;
 
   private renderChild = (child: React.ReactNode, spacing: number): React.ReactNode => {
     if (!React.isValidElement(child)) {
       return;
     }
 
-    if (child.type === Column) {
+    if (child.type === DeprecatedColumn) {
       const childProps = child.props;
 
       if (childProps.spacing || childProps.spacing === 0) {
@@ -96,4 +121,4 @@ export class Layout extends React.Component<LayoutProps> {
   }
 }
 
-Layout.Column = Column;
+DeprecatedLayout.Column = DeprecatedColumn;

package/layout/lib/Stack.tsx

@@ -62,9 +62,9 @@ export interface HStackProps extends StackProps {
 
 export const HStack = createComponent('div')({
   displayName: 'HStack',
-  Component: ({children, ...elemProps}: HStackProps, ref, Element) => {
+  Component: ({children, flexDirection = 'row', ...elemProps}: HStackProps, ref, Element) => {
     return (
-      <Stack as={Element} ref={ref} flexDirection="row" {...elemProps}>
+      <Stack as={Element} ref={ref} flexDirection={flexDirection} {...elemProps}>
         {children}
       </Stack>
     );
@@ -84,9 +84,9 @@ export interface VStackProps extends StackProps {
 
 export const VStack = createComponent('div')({
   displayName: 'VStack',
-  Component: ({children, ...elemProps}: VStackProps, ref, Element) => {
+  Component: ({children, flexDirection = 'column', ...elemProps}: VStackProps, ref, Element) => {
     return (
-      <Stack as={Element} ref={ref} flexDirection="column" {...elemProps}>
+      <Stack as={Element} ref={ref} flexDirection={flexDirection} {...elemProps}>
         {children}
       </Stack>
     );

package/layout/lib/utils/background.ts

@@ -0,0 +1,83 @@
+import {Property} from 'csstype';
+
+import {buildStyleFns, buildStylePropFn, StyleFnConfig} from './buildStyleFns';
+import {SystemPropValues} from './systemProps';
+
+/** style props to set CSS background properties */
+export type BackgroundStyleProps = {
+  /**
+   * - sets [CSS background property](https://developer.mozilla.org/en-US/docs/Web/CSS/background)
+   * - system tokens: `color`
+   * */
+  background?: SystemPropValues['color'];
+  /** sets [CSS background-attachment property](https://developer.mozilla.org/en-US/docs/Web/CSS/) */
+  backgroundAttachment?: Property.BackgroundAttachment;
+  /**
+   * - sets [CSS background-color property](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color)
+   * - system tokens: `color`
+   * */
+  backgroundColor?: SystemPropValues['color'];
+  /** sets [CSS background-image property](https://developer.mozilla.org/en-US/docs/Web/CSS/background-image) */
+  backgroundImage?: Property.BackgroundImage;
+  /** sets [CSS background-position property](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position) */
+  backgroundPosition?: Property.BackgroundPosition;
+  /** sets [CSS background-repeat property](https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat) */
+  backgroundRepeat?: Property.BackgroundRepeat;
+  /** sets [CSS background-size property](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size) */
+  backgroundSize?: Property.BackgroundSize;
+};
+
+export const backgroundStyleFnConfigs: StyleFnConfig[] = [
+  {
+    name: 'background',
+    properties: ['background'],
+    system: 'color',
+  },
+  {
+    name: 'backgroundAttachment',
+    properties: ['backgroundAttachment'],
+    system: 'none',
+  },
+  {
+    name: 'backgroundColor',
+    properties: ['backgroundColor'],
+    system: 'color',
+  },
+  {
+    name: 'backgroundImage',
+    properties: ['backgroundImage'],
+    system: 'none',
+  },
+  {
+    name: 'backgroundPosition',
+    properties: ['backgroundPosition'],
+    system: 'none',
+  },
+  {
+    name: 'backgroundRepeat',
+    properties: ['backgroundRepeat'],
+    system: 'none',
+  },
+  {
+    name: 'backgroundSize',
+    properties: ['backgroundSize'],
+    system: 'none',
+  },
+];
+
+export const backgroundFns = buildStyleFns(backgroundStyleFnConfigs);
+/**
+ * A style prop function that takes component props and returns border styles.
+ * Some props, such as background and backgroundColor, are connected to our design tokens.
+ * If no `BackgroundStyleProps` are found, it returns an empty object.
+ *
+ * @example
+ * ```tsx
+ * const BackgroundExample = () => (
+ *   <Box backgroundColor="blueberry500">
+ *     Hello, background styles!
+ *   </Box>
+ * );
+ *```
+ */
+export const background = buildStylePropFn<BackgroundStyleProps>(backgroundFns);

package/layout/lib/utils/border/color.ts

@@ -0,0 +1,85 @@
+import {buildStyleFns, StyleFnConfig} from '../buildStyleFns';
+import {SystemPropValues} from '../systemProps';
+
+/** style props to set CSS border color properties */
+export type BorderColorStyleProps = {
+  /**
+   * - sets [CSS border-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-color)
+   * - system tokens: `color`
+   */
+  borderColor?: SystemPropValues['color'];
+  /**
+   * - sets [CSS border-top-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-top-color)
+   * - system tokens: `color`
+   */
+  borderTopColor?: SystemPropValues['color'];
+  /**
+   * - sets [CSS border-right-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-right-color)
+   * - no bidirectional support
+   * - system tokens: `color`
+   */
+  borderRightColor?: SystemPropValues['color'];
+  /**
+   * - sets [CSS border-bottom-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color)
+   * - system tokens: `color`
+   */
+  borderBottomColor?: SystemPropValues['color'];
+  /**
+   * - sets [CSS border-left-color property]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-left-color)
+   * - no bidirectional support
+   * - system tokens: `color`
+   */
+  borderLeftColor?: SystemPropValues['color'];
+  /**
+   * - sets [CSS border-inline-start-color property ]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-start-color)
+   * - bidirectional support
+   * - system tokens: `color`
+   */
+  borderInlineStartColor?: SystemPropValues['color'];
+  /**
+   * - sets [CSS border-inline-end-color property ]((https://developer.mozilla.org/en-US/docs/Web/CSS/border-inline-end-color)
+   * - bidirectional support
+   * - system tokens: `color`
+   */
+  borderInlineEndColor?: SystemPropValues['color'];
+};
+
+export const borderColorStyleFnConfigs: StyleFnConfig[] = [
+  {
+    name: 'borderColor',
+    properties: ['borderColor'],
+    system: 'color',
+  },
+  {
+    name: 'borderTopColor',
+    properties: ['borderTopColor'],
+    system: 'color',
+  },
+  {
+    name: 'borderRightColor',
+    properties: ['borderRightColor'],
+    system: 'color',
+  },
+  {
+    name: 'borderBottomColor',
+    properties: ['borderBottomColor'],
+    system: 'color',
+  },
+  {
+    name: 'borderLeftColor',
+    properties: ['borderLeftColor'],
+    system: 'color',
+  },
+  {
+    name: 'borderInlineStartColor',
+    properties: ['borderInlineStartColor'],
+    system: 'color',
+  },
+  {
+    name: 'borderInlineEndColor',
+    properties: ['borderInlineEndColor'],
+    system: 'color',
+  },
+];
+
+export const borderColorFns = buildStyleFns(borderColorStyleFnConfigs);

package/layout/lib/utils/border/index.ts

@@ -0,0 +1,49 @@
+import {buildStylePropFn} from '../buildStyleFns';
+import {BorderColorStyleProps, borderColorFns, borderColorStyleFnConfigs} from './color';
+import {BorderLineStyleProps, borderLineStyleFns, borderLineStyleFnConfigs} from './lineStyle';
+import {BorderRadiusStyleProps, borderRadiusFns, borderRadiusStyleFnConfigs} from './radius';
+import {
+  BorderShorthandStyleProps,
+  borderShorthandFns,
+  borderShorthandStyleFnConfigs,
+} from './shorthand';
+import {BorderWidthStyleProps, borderWidthFns, borderWidthStyleFnConfigs} from './width';
+
+export type BorderStyleProps = BorderColorStyleProps &
+  BorderLineStyleProps &
+  BorderRadiusStyleProps &
+  BorderShorthandStyleProps &
+  BorderWidthStyleProps;
+
+/**
+ * A style prop function that takes component 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
+ * ```tsx
+ * const BorderExample = () => (
+ *   <Box
+ *    border="solid 1px"
+ *    borderColor="soap500"
+ *    borderRadius="l"
+ *   >
+ *     Hello, border styles!
+ *   </Box>
+ * );
+ *```
+ */
+export const border = buildStylePropFn<BorderStyleProps>({
+  ...borderColorFns,
+  ...borderLineStyleFns,
+  ...borderRadiusFns,
+  ...borderShorthandFns,
+  ...borderWidthFns,
+});
+
+export const borderStyleFnConfigs = [
+  ...borderColorStyleFnConfigs,
+  ...borderLineStyleFnConfigs,
+  ...borderRadiusStyleFnConfigs,
+  ...borderShorthandStyleFnConfigs,
+  ...borderWidthStyleFnConfigs,
+];