@workday/canvas-kit-docs 6.0.0-alpha.0-next.33 → 6.0.0-alpha.0-next.39

package/dist/mdx/6.0-MIGRATION-GUIDE.mdx

@@ -216,6 +216,9 @@ const CustomGlobalHeader = props => {
 };
 ```
 
+You may continue to use this component exactly as you did in v5, but note that we plan to hard-deprecate it in Canvas Kit v7.
+If you would like to migrate away from this deprecated component now, you can reference [this example](https://workday.github.io/canvas-kit/?path=/story/examples-global-header-react--basic) instead.
+
 ### Page Header
 
 We are [soft-deprecating](#soft-deprecation) `PageHeader`. It has been renamed to
@@ -267,6 +270,9 @@ export const CustomPageHeader = (props: CustomPageHeaderProps) => {
 };
 ```
 
+You may continue to use this component exactly as you did in v5, but note that we plan to hard-deprecate it in Canvas Kit v7.
+If you would like to migrate away from this deprecated component now, you can reference [this example](https://workday.github.io/canvas-kit/?path=/story/examples-page-header-react--basic) instead.
+
 ## Component Migrations
 
 ### Search Bar
@@ -337,7 +343,7 @@ type CustomDepthValues = CanvasDepthValue;
 interface OtherCustomDepthValues extends CanvasDepthValue {}
 
 // v6
-import {CanvasDepthValue} from '@workday/canvas-kit-react/tokens';
+import {CanvasDepthValues} from '@workday/canvas-kit-react/tokens';
 
 type CustomDepthValues = CanvasDepthValues;
 interface OtherCustomDepthValues extends CanvasDepthValues {}
@@ -363,10 +369,10 @@ Below is a reference table for the V5 and V6 breakpoint values.
 
 Also for reference, these are our viewport 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
+- `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
 
 ### Action Bar
 
@@ -374,10 +380,10 @@ Also for reference, these are our viewport ranges:
 `max-width: 575px`. They now use `max-width: 767.5px` – the upper limit of the `small` range. This
 will have two effects for this component:
 
-- Container padding will decrease from `s` (16px) to `xxs` (8px) on all viewports < 768px wide
-  - This was previously happening only on viewports < 576px wide
-- Button order will be reversed on all viewports < 768px wide
-  - This was previously happening only on viewports < 576px wide
+- Container padding will decrease from `s` (`16px`) to `xxs` (`8px`) on all viewports less than `768px` wide
+  - This was previously happening only on viewports less than `576px` wide
+- Button order will be reversed on all viewports less than `768px` wide
+  - This was previously happening only on viewports less than `576px` wide
 
 These changes in behavior are intentional and expected.
 
@@ -471,7 +477,7 @@ All these changes are described in detail by button type in the sections below.
 #### Primary Disabled State
 
 Previously the button's disabled state had a `blueberry200` background, but it now uses the default
-`blueberry400` and sets the entire button to 40% opacity. This creates more more consistency for the
+`blueberry400` and sets the entire button to 40% opacity. This creates more consistency for the
 disabled states across all our buttons.
 
 #### Primary Large
@@ -489,7 +495,7 @@ height of the button will remain the same.
 
 #### Primary Small
 
-We now support icons for small `PrimaryButton`s. The icons are `20px` x `20xpx`.
+We now support icons for small `PrimaryButton`s. The icons are `20px` x `20px`.
 
 #### Primary Extra Small
 
@@ -513,7 +519,7 @@ overall height of the button will remain the same.
 
 #### Secondary Small
 
-We now support icons for small `SecondaryButton`s. The icons are `20px` x `20xpx`.
+We now support icons for small `SecondaryButton`s. The icons are `20px` x `20px`.
 
 #### Secondary Extra Small
 

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

@@ -0,0 +1,33 @@
+# Canvas Kit 7.0 Migration Guide
+
+Below are the breaking changes made in Canvas Kit v7. Please
+[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
+any questions about the update.
+
+- [Codemod](#codemod)
+
+## Codemod
+
+Please use our [codemod package](https://github.com/Workday/canvas-kit/tree/master/modules/codemod)
+to automatically update your code to work with a majority of the breaking changes in the migration
+from Canvas Kit v6 to v7:
+
+```sh
+> npx @workday/canvas-kit-codemod v7 [path]
+```
+
+> Note: This codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` extensions. You may need to make
+> some manual changes in other file types (`.json`, `.mdx`, `.md`, etc.).
+
+> Note: You may need to run your linter after executing the codemod, as it's resulting formatting
+> (spacing, quotes, etc.) may not match your project's styling.
+
+**Breaking changes accounted for by this codemod will be marked with a 🤖.**
+
+**Please verify all changes made by the codemod. As a safety precaution, we recommend committing the
+changes from the codemod as a single isolated commit (separate from other changes) so you can
+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. The `@workday/canvas-kit-codemod` package will
+help us maintain additional codemod transforms to make future migrations easier.

package/dist/mdx/preview-react/form-field/FormField.mdx

@@ -0,0 +1,27 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+
+import {FormField} from '@workday/canvas-kit-preview-react/form-field';
+
+import Custom from './examples/Custom';
+
+
+# Canvas Kit Form Field
+
+FormField allows users to wrap input components to make them accessible. You usually won't want to
+use FormField directly but instead should use the specific component you need, e.g. `TextInput`.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Customizing With Behavior Hooks Example
+
+If you need full customization you can use the form field behavior hooks to build your own solution.
+It is also easy it work with custom components or third party libraries and get the CKR
+accessibility guarantees by using the `as` prop.
+
+<ExampleCodeBlock code={Custom} />

package/dist/mdx/preview-react/form-field/examples/Custom.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import {
+  useFormFieldHint,
+  useFormFieldInput,
+  useFormFieldLabel,
+  useFormFieldModel,
+  useFormFieldOrientation,
+  FormFieldModelContext,
+} from '@workday/canvas-kit-preview-react/form-field';
+import {useModelContext} from '@workday/canvas-kit-react/common';
+import {Stack} from '@workday/canvas-kit-labs-react/layout';
+
+const Label = ({model, children}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldLabel(localModel);
+
+  return (
+    <label {...props}>
+      {children}
+      {model.state.isRequired ? '*' : ''}
+    </label>
+  );
+};
+
+const Hint = ({model, children}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldHint(localModel);
+
+  return <span {...props}>{children}</span>;
+};
+
+const Input = ({model, ...elementProps}) => {
+  const localModel = useModelContext(FormFieldModelContext, model);
+  const props = useFormFieldInput(localModel, elementProps);
+
+  return <input type="text" required={model.state.isRequired ? true : false} {...props} />;
+};
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(event.target.value);
+  };
+
+  const model = useFormFieldModel({isRequired: true});
+
+  const layoutProps = useFormFieldOrientation('vertical')
+
+  return (
+    <Stack {...layoutProps}>
+      <Label model={model}>My Custom Field</Label>
+      <Input model={model} value={value} onChange={handleChange} />
+      <Hint model={model}>You can be anything</Hint>
+    </Stack>
+  );
+};

package/dist/mdx/preview-react/text-area/TextArea.mdx

@@ -0,0 +1,122 @@
+import {Specifications} from '@workday/canvas-kit-docs';
+
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+import Alert from './examples/Alert';
+import Basic from './examples/Basic';
+import Disabled from './examples/Disabled';
+import Error from './examples/Error';
+import Grow from './examples/Grow';
+import LabelPositionVertical from './examples/LabelPositionVertical';
+import LabelPositionHorizontal from './examples/LabelPositionHorizontal';
+import HiddenLabel from './examples/HiddenLabel';
+import Placeholder from './examples/Placeholder';
+import RefForwarding from './examples/RefForwarding';
+import Required from './examples/Required';
+import ResizeConstraints from './examples/ResizeConstraints';
+
+
+# Canvas Kit Text Area
+
+TextArea's allow users to enter and edit multiple lines of text.
+
+[> Workday Design Reference](https://design.workday.com/components/inputs/text-area)
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Basic Example
+
+<ExampleCodeBlock code={Basic} />
+
+### Disabled
+
+Use `TextArea.Field`'s `disabled` prop to prevent users from interacting with the field.
+
+<ExampleCodeBlock code={Disabled} />
+
+### Placeholder
+
+Use `TextArea.Field`'s `placeholder` prop to display a sample of its expected format or value before
+a value has been provided.
+
+<ExampleCodeBlock code={Placeholder} />
+
+### Required
+
+Use `TextArea.Field`'s `isRequired` prop (or use with the `useTextAreaModel` hook) to indicate that
+the field is required. This will also add a red asterisk to `TextArea.Label`.
+
+<ExampleCodeBlock code={Required} />
+
+### Ref Forwarding
+
+`TextArea` supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
+`ref` to its underlying `<textarea>` element.
+
+<ExampleCodeBlock code={RefForwarding} />
+
+### Resize Constraints
+
+Use the `resize` css attribute to restrict resizing of it to certain dimensions.
+
+<ExampleCodeBlock code={ResizeConstraints} />
+
+### Grow
+
+There are lots of ways to accomplish this. The `TextArea.Field` extends from Box so it is easy to
+extend full width, e.g. setting width prop to 100%, or you can set the `alignItems` prop to
+`stretch` on `TextArea`, etc.
+
+<ExampleCodeBlock code={Grow} />
+
+### Label Position
+
+Use the `orientation` property to set `TextArea.Label`'s position. You can override the default
+spacing using the `spacing` prop. Below are examples of both positions:
+
+#### Horizontal
+
+<ExampleCodeBlock code={LabelPositionHorizontal} />
+
+#### Vertical
+
+<ExampleCodeBlock code={LabelPositionVertical} />
+
+### Visually Hiding The Label
+
+If your label is just for screen reader users you can use the `accessibleHide` utility class from
+`@workday/canvas-kit-react/common`. You will likely want to set the `spacing` prop on `TextArea` to
+`zero`.
+
+<ExampleCodeBlock code={HiddenLabel} />
+
+### Error States
+
+Use the `hasError` property from `useTextAreaModel` to set the `TextArea` to the Error state. If you
+have an accompanying hint you can use the `TextArea.Hint` subcomponent.
+
+<ExampleCodeBlock code={Error} />
+
+### Other Visual States
+
+Use the `useThemedRing` hook to change the visual state of the `<textarea>` element.
+
+#### Alert
+
+<ExampleCodeBlock code={Alert} />
+
+## Props
+
+Undocumented props are spread to the underlying `<textarea>` element.
+
+<ArgsTable of={TextArea} />
+
+## Specifications
+
+<Specifications file="TextAreaPreview.spec.ts" name="Text Area" />

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

@@ -0,0 +1,31 @@
+/** @jsx jsx */
+import { jsx } from '@emotion/core'
+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';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value.slice(0, 10));
+  };
+
+  const alertStyles = useThemedRing(
+    value.length < 3 ? 'success' : value.length < 7 ? 'alert' : 'error'
+  );
+
+  const hintColor = value.length < 3 ? colors.greenApple600 : value.length < 7 ? colors.cantaloupe600 : colors.cinnamon500
+
+  return (
+    <TextArea orientation='vertical'>
+      <TextArea.Label>Add a comment</TextArea.Label>
+      <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>
+      </TextArea.Hint>
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field disabled onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,40 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+import {space} from '@workday/canvas-kit-react/tokens';
+
+export default () => {
+  const [value, setValue] = React.useState('four');
+  const [hint, setHint] = React.useState('');
+  const [hasError, setHasError] = React.useState(false);
+
+  const validateInput = (value: string) => {
+    const stringLength = value.length;
+    if (stringLength !== 3) {
+      setHasError(true);
+      const hintStart = 'Word length must be';
+      setHint(stringLength < 3 ? `${hintStart} greater than 2` : `${hintStart} less than 4`);
+    } else {
+      setHasError(false);
+      setHint('');
+    }
+  };
+
+  React.useEffect(() => {
+    validateInput(value);
+    // Only run on load
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    validateInput(event.target.value);
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea hasError={hasError} orientation='vertical'>
+      <TextArea.Label>A three letter word</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+      <TextArea.Hint paddingTop={space.xxs}>{hint}</TextArea.Hint>
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical' alignItems='stretch'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,20 @@
+/** @jsx jsx */
+import { jsx } from '@emotion/core'
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+import { accessibleHide } from '@workday/canvas-kit-react/common';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical' spacing='zero'>
+      <TextArea.Label css={{...accessibleHide}}>Email</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='horizontal'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical' spacing='xxxs'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,21 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field
+        placeholder="Let us know how we did!"
+        onChange={handleChange}
+        value={value}
+      />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import {changeFocus} from '@workday/canvas-kit-react/common';
+import {VStack} from '@workday/canvas-kit-labs-react/layout';
+import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+  const ref = React.useRef(null);
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  const handleClick = () => {
+    changeFocus(ref.current)
+  };
+
+  return (
+    <VStack spacing='xxxs' alignItems='flex-start'>
+      <TextArea orientation='vertical'>
+        <TextArea.Label>Leave a review</TextArea.Label>
+        <TextArea.Field onChange={handleChange} value={value} ref={ref} />
+      </TextArea>
+      <SecondaryButton onClick={handleClick}>Focus Text Area</SecondaryButton>
+    </VStack>
+  );
+};

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea isRequired={true} orientation='vertical'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <TextArea.Field onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};

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

@@ -0,0 +1,22 @@
+import React from 'react';
+import {TextArea} from '@workday/canvas-kit-preview-react/text-area';
+import {styled} from '@workday/canvas-kit-react/common';
+
+const StyledField = styled(TextArea.Field)({
+  resize: 'vertical',
+});
+
+export default () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <TextArea orientation='vertical'>
+      <TextArea.Label>Leave a review</TextArea.Label>
+      <StyledField onChange={handleChange} value={value} />
+    </TextArea>
+  );
+};