@workday/canvas-kit-docs 8.0.0-alpha.144-next.0 → 8.0.0-alpha.151-next.3

package/dist/mdx/8.0-UPGRADE-GUIDE.mdx

@@ -1,10 +1,12 @@
-# Canvas Kit 7.0 Upgrade Guide
+# Canvas Kit 8.0 Upgrade Guide
 
-This guide contains breaking changes in Canvas Kit v7. Please
+This guide contains breaking changes in Canvas Kit v8. Please
 [reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
 any questions.
 
 - [Codemod](#codemod)
+- [Components](#components)
+  - [Box](#box)
 - [General Changes](#general-changes) -[Remove Default Imports](#remove-default-imports)
 
 ## Codemod
@@ -32,6 +34,30 @@ rollback more easily if necessary.**
 [Let us know](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you
 encounter any issues or use cases that we've missed.
 
+## Components
+
+### Box
+
+#### Updating props
+
+The following props have been added to the `Box` component to support font and text styles:
+`fontFamily`, `fontSize`, `fontStyle`, `fontWeight`, `lineHeight`, `letterSpacing`, `textAlign`,
+`textDecoration`, `textTransform`, `textShadow`, `whiteSpace`, `wordBreak`.
+
+```tsx
+// v7
+const StyledBox = styled(Box)({
+  fontFamily: 'monospace',
+  fontSize: type.properties.fontSizes[16],
+  fontWeight: type.properties.fontWeights.medium
+})
+
+<StyledBox />
+
+// v8
+<Box fontFamily="monospace" fontSize={16} fontWeight="medium" />
+```
+
 ## General Changes
 
 ### Remove Default Imports

package/dist/mdx/preview-react/_examples/examples/SidePanelWithOverlay.tsx

@@ -1,14 +1,9 @@
 import * as React from 'react';
 import {styled} from '@workday/canvas-kit-react/common';
-import {colors, depth, type} from '@workday/canvas-kit-react/tokens';
+import {depth} from '@workday/canvas-kit-react/tokens';
 import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex, Box} from '@workday/canvas-kit-react/layout';
-
-const StyledHeader = styled('h3')({
-  ...type.levels.body.large,
-  color: colors.licorice500,
-  fontWeight: type.properties.fontWeights.bold,
-});
+import {Text} from '@workday/canvas-kit-react/text';
 
 const StyledPanel = styled(SidePanel)({
   ...depth[6],
@@ -22,7 +17,9 @@ export default () => {
     <Flex height={320} backgroundColor="soap100" position="relative">
       <StyledPanel touched={true} variant="alternate">
         <Flex alignItems="center" paddingY="s" paddingX="s">
-          <StyledHeader {...labelProps}>Alternate Panel</StyledHeader>
+          <Text as="h3" typeLevel="body.large" fontWeight="bold" color="licorice500">
+            Alternate Panel
+          </Text>
         </Flex>
       </StyledPanel>
       <Box position="absolute" background="rgba(0,0,0,0.65)" height="100%" width="100%" />

package/dist/mdx/preview-react/side-panel/examples/AlwaysOpen.tsx

@@ -1,16 +1,11 @@
 import * as React from 'react';
-import {colors, space, type} from '@workday/canvas-kit-react/tokens';
+import {styled} from '@workday/canvas-kit-react/common';
+import {space} from '@workday/canvas-kit-react/tokens';
 import {AccentIcon} from '@workday/canvas-kit-react/icon';
 import {rocketIcon} from '@workday/canvas-accent-icons-web';
 import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex, HStack} from '@workday/canvas-kit-react/layout';
-import {styled} from '@workday/canvas-kit-react/common';
-
-const StyledHeader = styled('h3')({
-  ...type.levels.body.large,
-  color: colors.licorice500,
-  fontWeight: type.properties.fontWeights.bold,
-});
+import {Text} from '@workday/canvas-kit-react/text';
 
 const StyledAccentIcon = styled(AccentIcon)({
   marginRight: space.s,
@@ -24,7 +19,15 @@ export default () => {
       <SidePanel {...panelProps}>
         <Flex alignItems="center" paddingY="s" paddingX="s">
           <StyledAccentIcon icon={rocketIcon} />
-          <StyledHeader {...labelProps}>Tasks Panel</StyledHeader>
+          <Text
+            as="h3"
+            typeLevel="body.large"
+            color="licorice500"
+            fontWeight="bold"
+            {...labelProps}
+          >
+            Tasks Panel
+          </Text>
         </Flex>
       </SidePanel>
     </HStack>

package/dist/mdx/preview-react/side-panel/examples/Basic.tsx

@@ -1,5 +1,4 @@
 import * as React from 'react';
-import {colors, type} from '@workday/canvas-kit-react/tokens';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {
   SidePanel,
@@ -7,18 +6,13 @@ import {
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {CanvasProvider, styled} from '@workday/canvas-kit-react/common';
+import {Text} from '@workday/canvas-kit-react/text';
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
 import {AccentIcon} from '@workday/canvas-kit-react/icon';
 import {rocketIcon} from '@workday/canvas-accent-icons-web';
 // local helper hook for setting content direction;
 import {useDirection} from './useDirection';
 
-const StyledHeader = styled('h3')({
-  ...type.levels.body.large,
-  color: colors.licorice500,
-  fontWeight: type.properties.fontWeights.bold,
-});
-
 export default () => {
   const {direction, toggleDirection} = useDirection();
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
@@ -36,7 +30,15 @@ export default () => {
               <Flex marginInlineEnd="s">
                 <AccentIcon icon={rocketIcon} />
               </Flex>
-              <StyledHeader {...labelProps}>Tasks Panel</StyledHeader>
+              <Text
+                as="h3"
+                typeLevel="body.large"
+                color="licorice500"
+                fontWeight="bold"
+                {...labelProps}
+              >
+                Tasks Panel
+              </Text>
             </Flex>
           )}
         </SidePanel>

package/dist/mdx/preview-react/side-panel/examples/ExternalControl.tsx

@@ -5,15 +5,8 @@ import {
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {Text} from '@workday/canvas-kit-react/text';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
-import {colors, type} from '@workday/canvas-kit-react/tokens';
-import {styled} from '@workday/canvas-kit-react/common';
-
-const StyledHeader = styled('h3')({
-  ...type.levels.body.large,
-  color: colors.licorice500,
-  fontWeight: type.properties.fontWeights.bold,
-});
 
 export default () => {
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel({initialExpanded: false});
@@ -33,7 +26,15 @@ export default () => {
       >
         {panelState === 'expanded' && (
           <Flex alignItems="center" paddingY="s" paddingX="s">
-            <StyledHeader {...labelProps}>Tasks Panel</StyledHeader>
+            <Text
+              as="h3"
+              typeLevel="body.large"
+              color="licorice500"
+              fontWeight="bold"
+              {...labelProps}
+            >
+              Tasks Panel
+            </Text>
           </Flex>
         )}
       </SidePanel>

package/dist/mdx/preview-react/side-panel/examples/RightOrigin.tsx

@@ -1,5 +1,4 @@
 import * as React from 'react';
-import {colors, type} from '@workday/canvas-kit-react/tokens';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {
   SidePanel,
@@ -7,16 +6,11 @@ import {
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {Text} from '@workday/canvas-kit-react/text';
 import {CanvasProvider, styled} from '@workday/canvas-kit-react/common';
 // local helper hook for setting content direction;
 import {useDirection} from './useDirection';
 
-const StyledHeader = styled('h3')({
-  ...type.levels.body.large,
-  color: colors.licorice500,
-  fontWeight: type.properties.fontWeights.bold,
-});
-
 const StyledSidePanel = styled(SidePanel)({
   marginLeft: 'auto',
 });
@@ -32,7 +26,15 @@ const RightPanel = () => {
       <SidePanel.ToggleButton {...controlProps} />
       {panelState === 'expanded' && (
         <Flex alignItems="center" justifyContent="flex-end" paddingY="s" paddingX="s">
-          <StyledHeader {...labelProps}>Tasks Panel</StyledHeader>
+          <Text
+            as="h3"
+            typeLevel="body.large"
+            color="licorice500"
+            fontWeight="bold"
+            {...labelProps}
+          >
+            Tasks Panel
+          </Text>
         </Flex>
       )}
     </StyledSidePanel>

package/dist/mdx/preview-react/side-panel/examples/Variant.tsx

@@ -1,5 +1,4 @@
 import * as React from 'react';
-import {colors, type} from '@workday/canvas-kit-react/tokens';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
 import {
   SidePanel,
@@ -7,16 +6,11 @@ import {
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {CanvasProvider, styled} from '@workday/canvas-kit-react/common';
+import {Text} from '@workday/canvas-kit-react/text';
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
 // local helper hook for setting content direction;
 import {useDirection} from './useDirection';
 
-const StyledHeader = styled('h3')({
-  ...type.levels.body.large,
-  color: colors.licorice500,
-  fontWeight: type.properties.fontWeights.bold,
-});
-
 export default () => {
   const {direction, toggleDirection} = useDirection();
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
@@ -31,7 +25,15 @@ export default () => {
           <SidePanel.ToggleButton {...controlProps} />
           {panelState === 'expanded' && (
             <Flex alignItems="center" paddingY="s" paddingX="s">
-              <StyledHeader {...labelProps}>Alternate Panel</StyledHeader>
+              <Text
+                as="h3"
+                typeLevel="body.large"
+                color="licorice500"
+                fontWeight="bold"
+                {...labelProps}
+              >
+                Alternate Panel
+              </Text>
             </Flex>
           )}
         </SidePanel>

package/dist/mdx/preview-react/text-area/examples/Alert.tsx

@@ -5,9 +5,10 @@ import React from 'react';
 import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
 import {useThemedRing} from '@workday/canvas-kit-labs-react/common';
 import {space, colors} from '@workday/canvas-kit-react/tokens';
+import {Text} from '@workday/canvas-kit-react/text';
 
 export default () => {
-  const [value, setValue] = React.useState('');
+  const [value, setValue] = React.useState('Hello');
 
   const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
     setValue(event.target.value.slice(0, 10));
@@ -30,7 +31,7 @@ export default () => {
       <TextArea.Field css={alertStyles} onChange={handleChange} value={value} />
       <TextArea.Hint paddingTop={space.xxs}>
         <strong>Character Limit: </strong>
-        <span css={{color: hintColor}}>{10 - value.length} Left</span>
+        <Text color={hintColor}>{10 - value.length} Left</Text>
       </TextArea.Hint>
     </TextArea>
   );

package/dist/mdx/react/_examples/examples/PageHeader.tsx

@@ -1,11 +1,12 @@
 import * as React from 'react';
 import {createComponent, styled} from '@workday/canvas-kit-react/common';
 
-import {colors, gradients, space, type} from '@workday/canvas-kit-react/tokens';
+import {colors, gradients, space} from '@workday/canvas-kit-react/tokens';
 
 import {HStack, HStackProps, StackSpacing} from '@workday/canvas-kit-react/layout';
 import {TertiaryButton} from '@workday/canvas-kit-react/button';
 import {justifyIcon, notificationsIcon} from '@workday/canvas-system-icons-web';
+import {Heading} from '@workday/canvas-kit-react/text';
 
 interface HeaderItemProps extends Omit<HStackProps, 'spacing'> {
   spacing?: StackSpacing;
@@ -31,9 +32,18 @@ const PageHeaderItem = createComponent('div')({
 const PageHeaderTitle = createComponent('h2')({
   displayName: 'PageHeader.Title',
   Component: ({children, ...props}, ref, Element) => (
-    <Title ref={ref} as={Element} {...props}>
+    <Heading
+      as={Element}
+      ref={ref}
+      size="medium"
+      variant="inverse"
+      padding={`${space.xs} 0`}
+      margin={0}
+      whiteSpace="nowrap"
+      {...props}
+    >
       {children}
-    </Title>
+    </Heading>
   ),
 });
 
@@ -53,11 +63,3 @@ const Header = styled('header')({
   alignItems: 'center',
   justifyContent: 'space-between',
 });
-
-const Title = styled('h2')({
-  ...type.levels.heading.medium,
-  color: colors.frenchVanilla100,
-  padding: `${space.xs} 0`,
-  margin: 0,
-  whiteSpace: 'nowrap',
-});

package/dist/mdx/react/layout/Box.mdx

@@ -3,12 +3,14 @@ import {Box} from '@workday/canvas-kit-react/layout';
 import As from './examples/As';
 import Border from './examples/Border';
 import Color from './examples/Color';
+import Font from './examples/Font';
 import Depth from './examples/Depth';
 import FlexItem from './examples/FlexItem';
 import Layout from './examples/Layout';
 import Position from './examples/Position';
 import Ref from './examples/Ref';
 import Space from './examples/Space';
+import Text from './examples/Text';
 // props tables
 import {
   BoxBorder,
@@ -60,16 +62,20 @@ is highly flexible, and its primary purpose is to build other components.
       - [Example](#example-2)
     - [Flex Item](#flex-item)
       - [Example](#example-3)
-    - [Layout](#layout)
+    - [Font](#font)
       - [Example](#example-4)
+    - [Layout](#layout)
+      - [Example](#example-5)
     - [Position](#position)
       - [Position Logical Props](#position-logical-props)
       - [Position Standard Props](#position-standard-props)
-      - [Example](#example-5)
+      - [Example](#example-6)
     - [Space](#space)
       - [Space Logical Props](#space-logical-props)
       - [Space Standard Props](#space-standard-props)
-      - [Example](#example-6)
+      - [Example](#example-7)
+    - [Text](#space)
+      - [Example](#example-8)
   - [Exhaustive Style Prop List](#exhaustive-style-prop-list)
     - [Border Props](#border-props)
     - [Color Props](#color-props)
@@ -273,6 +279,16 @@ table for flex item props:
 
 ---
 
+### Font
+
+Font style props allow you to adjust the font family, style, size or weight of components.
+
+#### Example
+
+<ExampleCodeBlock code={Font} />
+
+---
+
 ### Layout
 
 Layout style props allow you to adjust the display, dimensions, and overflow of a component. These
@@ -372,6 +388,17 @@ Bidirectional support will only affect `marginLeft`, `marginRight`, `paddingLeft
 
 <ExampleCodeBlock code={Space} />
 
+### Text
+
+Text style props allow you to modify text using props such as `textDecoration` or `textTransform` or
+set line styles by `lineHeight` or `letterSpacing`, etc.
+
+#### Example
+
+<ExampleCodeBlock code={Text} />
+
+---
+
 ## Exhaustive Style Prop List
 
 Below is an exhaustive list of `Box` style props divided by category.

package/dist/mdx/react/layout/Grid.mdx

@@ -0,0 +1,130 @@
+import {Grid, GridItem} from '@workday/canvas-kit-react/layout';
+// examples
+import GridLayout from './examples/Grid/GridLayout';
+import UIExample from './examples/Grid/UIExample';
+import GridLayoutInteractive from './examples/Grid/GridLayoutInteractive';
+import {GridStyle} from './examples/PropTables.splitprops.tsx';
+import {GridStyleProps} from '../lib/utils/grid';
+import {GridItemStyleProps} from '../lib/utils/gridItem';
+
+
+# Canvas Kit Grid
+
+`Grid` is a low-level layout component that provides a common, ergonomic API for building
+two-dimensional layouts (rows and columns) with
+[CSS Grid](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids).
+
+If you want to see how Flexbox and Grid can
+[work together](https://css-tricks.com/css-grid-replace-flexbox/).
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-react
+```
+
+## Usage
+
+### Basic Example
+
+Below is a basic layout built with `Grid`. We created four components: `Header`, `SideBar`,
+`BodyContent` and `Footer`. We also used those names for their respective `gridArea` props. Then we
+can use those names in the parent component, `UIExample`, to organize the UI however we want. This
+allows the parent container to control how its children render. For page layouts, Workday typically
+uses a 12 column grid. In the example below, the Sidebar is 3 columns and the Body Content is 9
+columns.
+
+> Note: You can learn more about CSS Grid's `gridArea` and `gridTemplateAreas`
+> [here](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-areas).
+
+<ExampleCodeBlock code={UIExample} />
+
+### Using Grid Items
+
+In the example above we nested `Grid` components to create our layout, and we controlled the layout
+structure from the top-level `Grid` container. That's a perfectly valid approach. However, we can
+also use `Grid.Item` components to allow child cells to have more control. While any direct child of
+a `Grid` component is implicitly a grid item, `Grid.Item` provides special CSS Grid Item style props
+that allow you to have more control over how and where each item renders.
+
+To demonstrate this behavior, the example below has a `Grid` container with nine cells. The eight
+`soap500` cells are `Grid` components, and the `peach300` cell is a `Grid.Item`. We can use the
+`Grid.Item` style props `gridRowStart` and `gridColumnStart` to manipulate where the cell renders.
+You can use the `Row` and `Column` buttons to manipulate these props and see the `Grid.Item`'s
+position adjust accordingly.
+
+> Note: This example is solely intended to demonstrate the `Grid.Item`'s functionality and is NOT
+> considered an accessibility best practice. Visually reordering content does not change the order
+> it is read by a screen reader or the tab order. You can learn more about CSS Grid layout and
+> accessibility
+> [here](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/CSS_Grid_Layout_and_Accessibility).
+
+<ExampleCodeBlock code={GridLayoutInteractive} />
+
+Let's look at another `Grid.Item` example. Below, we have a `Grid` container with two rows: one with
+seven elements and the other with two elements. This example is to show how a user can use the
+`<Grid.Item/>` component to wrap a `Grid` component. This would allow a user to have access to the
+child props of `Grid.Item` to place a layout where needed. The row with elements 3 - 7 is put before
+the 1 & 2 elements since that layout is wrapped by the `Grid.Item` component.
+
+<ExampleCodeBlock code={GridLayout} />
+
+### Using Grid vs. Flex vs. Box
+
+`Box` is the underlying layout component that `Grid` and `Flex` are built upon. So `Grid` and `Flex`
+have access to all `BoxProps`. But `Grid` and `Flex` have their own specific style props that map to
+CSS Grid and Flexbox properties, respectively. When using these components to build layouts, it is
+not a matter of choosing `Grid` _or_ `Flex` _or_ `Box`, but rather deciding how to use them
+together. They are intended to be complementary not exclusionary. With that said, here are some
+general rules for when to use which:
+
+- Use `Grid` for building **two-dimensional** layouts (rows AND columns).
+- Use `Flex` for building **one-dimensional** layouts (a row OR a column).
+- Use `Box` for generic containers that don't need CSS Flexbox or Grid.
+
+## Components
+
+### Grid
+
+Grid is a container component for creating two-dimensional layouts with CSS Grid. It has special
+style props that map to CSS Grid style properties to provide a common, ergonomic API for building
+layouts.
+
+#### Usage
+
+```tsx
+<Grid grid gridTemplateColumns="1fr 2fr 1fr" gridGap={space.s}>
+  <div>Implicit grid item 1</div>
+  <div>Implicit grid item 2</div>
+  <div>Implicit grid item 3</div>
+</Grid>
+```
+
+#### Props
+
+As previously mentioned, `Grid` is built on top of `Box` and has access to all its props, including
+[grid container properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Basic_Concepts_of_Grid_Layout#the_grid_container)
+through style props as well. Here are the grid container props:
+
+<ArgsTable of={GridStyleProps} />
+
+### Grid.Item
+
+`Grid.Item` is a subcomponent of Grid. It has specific grid item style props that map to CSS Grid
+Item properties. This allows you greater control over how child components render in your layout.
+
+#### Usage
+
+```tsx
+<Grid gridGap={space.s}>
+  <Grid.Item gridColumn="1 / span 2">First item</Grid.Item>
+  <Grid.Item gridRow="1 / span 2">Second item</Grid.Item>
+  <Grid.Item gridColumn="1 / span 2" gridRow="2">
+    Third item
+  </Grid.Item>
+</Grid>
+```
+
+#### Props
+
+<ArgsTable of={GridItemStyleProps} />

package/dist/mdx/react/layout/examples/Flex/FlexCard.tsx

@@ -1,21 +1,7 @@
 import * as React from 'react';
 import {Flex, Box} from '@workday/canvas-kit-react/layout';
 import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
-import {type} from '@workday/canvas-kit-react/tokens';
-
-// temporary placeholder until type components are added to canvas-kit
-const H3 = props => (
-  <h3
-    style={{
-      ...type.levels.body.large,
-      margin: 0,
-      fontWeight: type.properties.fontWeights.bold,
-    }}
-    {...props}
-  />
-);
-
-const Body = props => <p style={{...type.levels.body.small, margin: 0}} {...props} />;
+import {BodyText} from '@workday/canvas-kit-react/text';
 
 export default () => {
   const [isComplete, setIsComplete] = React.useState(false);
@@ -29,10 +15,12 @@ export default () => {
       borderColor="soap400"
       maxWidth={600}
     >
-      <H3>Learn about Flex {isComplete && '🥳'}</H3>
-      <Box paddingY="s">
-        <Body>Complete this task when you have a functional understanding of Flex.</Body>
-      </Box>
+      <BodyText as="h3" size="large" fontWeight="bold" margin={0}>
+        Learn about Flex {isComplete && '🥳'}
+      </BodyText>
+      <BodyText size="small" margin={0} paddingY="s">
+        Complete this task when you have a functional understanding of Flex.
+      </BodyText>
       <Flex justifyContent="flex-end">
         <Box marginRight="xxs">
           <PrimaryButton onClick={() => setIsComplete(true)}>Complete</PrimaryButton>