@workday/canvas-kit-docs 8.0.0-alpha.138-next.6 → 8.0.0-alpha.150-next.2

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

@@ -431,7 +431,9 @@ The APIs for these promoted components remain unchanged.
 
 ### Action Bar
 
-The ActionBar API changed to model API to support more generic behaviors to allow for other
+#### Model
+
+The `ActionBar` API changed to model API to support more generic behaviors to allow for other
 components to support responsive layouts using the same models and behaviors. It also allows to
 implement a responsive layout based on a container width
 ([#1585](https://github.com/Workday/canvas-kit/pull/1585)).
@@ -449,7 +451,9 @@ const model = useActionBarModel({
 <ActionBar model={model} />;
 ```
 
-The ActionBar component can now handle responsive containers, but the support is not automatic. You
+#### Responsive Container Support
+
+The `ActionBar` component can now handle responsive containers, but the support is not automatic. You
 must use the dynamic API and provide an overflow menu subcomponent. The dynamic API doesn't know the
 shape of your object, so render props must be used to instruct React how to render each item.
 
@@ -497,6 +501,11 @@ const model = useActionBarModel({items});
 </ActionBar>;
 ```
 
+#### Fixed Position Prop
+
+`ActionBar`'s boolean `fixed` prop has been removed. It has been replaced by a new `position` style
+prop in the `ActionBar.List` component and is set to `fixed` by default.
+
 🤖 The codemod will remove uses of the `fixed` prop from `ActionBar` and restructure component by
 creating `ActionBar.List` subcomponent and replacing all `ActionBar` children to it.
 

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/Grid/GridCard.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import {Grid, 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} />;
+
+export default () => {
+  const [isComplete, setIsComplete] = React.useState(false);
+  return (
+    <Grid
+      padding="m"
+      depth={1}
+      borderRadius="l"
+      border="solid 1px"
+      borderColor="soap400"
+      maxWidth={600}
+      gridTemplate="auto / auto"
+    >
+      <H3>Learn about Grid {isComplete && '🥳'}</H3>
+      <Box paddingY="s">
+        <Body>Complete this task when you have a functional understanding of Grid.</Body>
+      </Box>
+      <Grid gridTemplate="auto / 1fr auto" justifyItems="end">
+        <Box marginRight="xxs">
+          <PrimaryButton onClick={() => setIsComplete(true)}>Complete</PrimaryButton>
+        </Box>
+        <SecondaryButton onClick={() => setIsComplete(false)}>Cancel</SecondaryButton>
+      </Grid>
+    </Grid>
+  );
+};

package/dist/mdx/react/layout/examples/Grid/GridLayout.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import {Grid} from '@workday/canvas-kit-react/layout';
+
+const Cell = (props: {children: React.ReactNode}) => {
+  return (
+    <Grid
+      alignContent="center"
+      padding="xs"
+      justifyContent="center"
+      backgroundColor="soap500"
+      color="blackPepper500"
+      borderRadius="m"
+    >
+      {props.children}
+    </Grid>
+  );
+};
+
+const CellItem = (props: {children: React.ReactNode}) => {
+  return (
+    <Grid
+      alignContent="center"
+      gridAutoColumns="max-content"
+      gridGap="0 16px"
+      height="100%"
+      gridAutoFlow="column"
+      padding="xs"
+      justifyContent="center"
+      backgroundColor="peach300"
+      color="blackPepper500"
+      borderRadius="m"
+    >
+      {props.children}
+    </Grid>
+  );
+};
+
+export default () => {
+  return (
+    <Grid gridAutoFlow="row" padding="xs" gridGap="10px 0">
+      <Grid
+        gridTemplateColumns="repeat(auto-fit, minmax(300px, 1fr))"
+        gridGap="10px"
+        padding="xxs"
+        border="5px solid #c860d1"
+      >
+        <Grid.Item gridRowStart="2">
+          <Grid gridTemplateColumns="repeat(auto-fit, minmax(300px, 1fr))" gridGap="10px">
+            <Cell>1</Cell>
+            <Cell>2</Cell>
+          </Grid>
+        </Grid.Item>
+        <Grid.Item gridRowStart="1">
+          <Grid gridTemplateColumns="repeat(auto-fit, minmax(100px, 1fr))" gridGap="10px">
+            <CellItem>3</CellItem>
+            <CellItem>4</CellItem>
+            <CellItem>5</CellItem>
+            <CellItem>6</CellItem>
+            <CellItem>7</CellItem>
+          </Grid>
+        </Grid.Item>
+      </Grid>
+    </Grid>
+  );
+};

package/dist/mdx/react/layout/examples/Grid/GridLayoutInteractive.tsx

@@ -0,0 +1,114 @@
+import React, {useState, useEffect, useRef} from 'react';
+import {Grid} from '@workday/canvas-kit-react/layout';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+// eslint-disable-next-line no-duplicate-imports
+import {
+  arrowDownIcon,
+  arrowLeftIcon,
+  arrowRightIcon,
+  arrowUpIcon,
+} from '@workday/canvas-system-icons-web';
+
+const Cell = (props: {children: React.ReactNode}) => {
+  return (
+    <Grid
+      alignContent="center"
+      padding="xs"
+      justifyContent="center"
+      backgroundColor="soap500"
+      color="blackPepper500"
+      borderRadius="m"
+    >
+      {props.children}
+    </Grid>
+  );
+};
+
+const CellItem = (props: {children: React.ReactNode}) => {
+  return (
+    <Grid
+      alignContent="center"
+      gridAutoColumns="max-content"
+      gridGap="0 16px"
+      height="100%"
+      gridAutoFlow="column"
+      padding="xs"
+      justifyContent="center"
+      backgroundColor="peach300"
+      color="frenchVanilla100"
+      borderRadius="m"
+    >
+      {props.children}
+    </Grid>
+  );
+};
+
+export default () => {
+  const [rowCount, setRowCount] = useState(1);
+  const [colCount, setColCount] = useState(1);
+
+  const Prev = val => {
+    const ref = useRef();
+    useEffect(() => {
+      ref.current = val;
+    }, [val]);
+    return ref.current;
+  };
+
+  const prevRowCount = Prev(rowCount);
+  const prevColCount = Prev(colCount);
+
+  const plusMinus = (curr, prev) => {
+    if (curr <= 2 && (!prev || prev <= 2)) {
+      return true;
+    }
+  };
+
+  const incDec = (curr, prev, func) => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    plusMinus(curr, prev) ? func(curr + 1) : func(curr - 1);
+  };
+
+  return (
+    <Grid gridAutoFlow="row" padding="xs" gridGap="10px 0">
+      <Grid
+        gridTemplateColumns="repeat(3, 1fr)"
+        gridTemplateRows="repeat(3, 1fr)"
+        gridGap="10px"
+        padding="xs"
+        border="5px solid #c860d1"
+      >
+        <Grid.Item gridRowStart={rowCount} gridColumnStart={colCount}>
+          <CellItem>
+            <PrimaryButton
+              size="extraSmall"
+              icon={plusMinus(rowCount, prevRowCount) ? arrowDownIcon : arrowUpIcon}
+              onClick={() => {
+                incDec(rowCount, prevRowCount, setRowCount);
+              }}
+            >
+              Row: {rowCount}
+            </PrimaryButton>
+            <PrimaryButton
+              size="extraSmall"
+              icon={plusMinus(colCount, prevColCount) ? arrowRightIcon : arrowLeftIcon}
+              onClick={() => {
+                incDec(colCount, prevColCount, setColCount);
+              }}
+            >
+              Col: {colCount}
+            </PrimaryButton>
+          </CellItem>
+        </Grid.Item>
+        <Cell>2</Cell>
+        <Cell>3</Cell>
+        <Cell>4</Cell>
+        <Cell>5</Cell>
+        <Cell>6</Cell>
+        <Cell>7</Cell>
+        <Cell>8</Cell>
+        <Cell>9</Cell>
+      </Grid>
+    </Grid>
+  );
+};

package/dist/mdx/react/layout/examples/Grid/UIExample.tsx

@@ -0,0 +1,71 @@
+import * as React from 'react';
+import {Grid, GridProps, Box} from '@workday/canvas-kit-react/layout';
+import {type} from '@workday/canvas-kit-react/tokens';
+import {fontSizes} from '../../../../tokens/lib/type/fontSizes';
+import styled from '@emotion/styled';
+
+// temporary placeholder until type components are added to canvas-kit
+
+const StyledHeading = styled(Box.as('h3'))({
+  ...type.levels.body.large,
+  ...type.variants.inverse,
+  margin: 0,
+  fontWeight: type.properties.fontWeights.bold,
+});
+
+const borderPadProps = {
+  borderRadius: 'm',
+  padding: 's',
+};
+
+const Header = ({children, ...props}: GridProps) => (
+  <Grid gridArea="Header" depth={1} {...props} {...borderPadProps}>
+    {children}
+  </Grid>
+);
+
+const BodyContent = ({children, ...props}: GridProps) => (
+  <Grid gridArea="BodyContent" depth={1} {...props} {...borderPadProps}>
+    {children}
+  </Grid>
+);
+
+const SideBar = ({children, ...props}: GridProps) => (
+  <Grid gridArea="SideBar" depth={1} {...props} {...borderPadProps}>
+    {children}
+  </Grid>
+);
+
+const Footer = ({children, ...props}: GridProps) => (
+  <Grid gridArea="Footer" depth={1} {...props} {...borderPadProps}>
+    {children}
+  </Grid>
+);
+
+export default () => {
+  const parentCont = {
+    gridTemplateAreas:
+      "'Header Header Header Header' 'SideBar BodyContent BodyContent BodyContent' 'Footer Footer Footer Footer'",
+    gridGap: fontSizes[16],
+    gridTemplateColumns: '3fr 9fr',
+    gridTemplateRows: 'auto 300px auto',
+  };
+  return (
+    <Grid as="section" padding="s">
+      <Grid {...parentCont}>
+        <Header backgroundColor="blueberry400">
+          <StyledHeading>Header</StyledHeading>
+        </Header>
+        <SideBar backgroundColor="blueberry300">
+          <StyledHeading>SideBar</StyledHeading>
+        </SideBar>
+        <BodyContent backgroundColor="plum300">
+          <StyledHeading>Body Content</StyledHeading>
+        </BodyContent>
+        <Footer backgroundColor="berrySmoothie300">
+          <StyledHeading>Footer</StyledHeading>
+        </Footer>
+      </Grid>
+    </Grid>
+  );
+};

package/dist/mdx/react/layout/examples/PropTables.splitprops.tsx

@@ -1,7 +1,9 @@
 import React from 'react';
 
-import {FlexStyleProps, StackStyleProps} from '@workday/canvas-kit-react/layout';
+import {FlexStyleProps, StackStyleProps, GridStyleProps} from '@workday/canvas-kit-react/layout';
 
 export const FlexStyle = (props: FlexStyleProps) => <div />;
 
 export const StackStyle = (props: StackStyleProps) => <div />;
+
+export const GridStyle = (props: GridStyleProps) => <div />;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "8.0.0-alpha.138-next.6+7e99b1d8",
+  "version": "8.0.0-alpha.150-next.2+b0c3f340",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -42,7 +42,7 @@
   ],
   "dependencies": {
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-react": "^8.0.0-alpha.138-next.6+7e99b1d8"
+    "@workday/canvas-kit-react": "^8.0.0-alpha.150-next.2+b0c3f340"
   },
   "devDependencies": {
     "fs-extra": "^10.0.0",
@@ -50,5 +50,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "4.1"
   },
-  "gitHead": "7e99b1d8e866a65d922bad07765622457b8712f6"
+  "gitHead": "b0c3f340ec8e06d39bed5d992b23a1b36892106f"
 }