@workday/canvas-kit-docs 12.0.0-alpha.862-next.0 → 12.0.0-alpha.898-next.0

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

@@ -13,7 +13,7 @@ any questions.
 
 ## Why You Should Upgrade
 
-Canvas Kit v12 is transitioning into a
+Canvas Kit is transitioning into a
 [new way of styling](https://github.com/Workday/canvas-kit/discussions/2265). Theming and building
 an in sync Canvas Kit CSS has been at the top of our minds. We've started using our new
 [Canvas Tokens Web](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
@@ -23,27 +23,29 @@ provide semantic tokens that can translate to theming components.
 
 A note to the reader:
 
-- While we still support our old tokens from `@workday/canvas-kit-react/tokens` in v12, you must
+- While we still support our old tokens from `@workday/canvas-kit-react/tokens`, **you must**
   install our new tokens from `@workday/canvas-tokens-web`. You can find more info in our
   [docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
-- In this release, we've introduced a
-  [new styling API](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-stencil).
-  This shouldn't effect the way you currently style your components. Because we're moving away from
-  Emotion, support for style props will eventually be removed, however, this API provide backwards
-  compatability. If you want to slowly move off of Emotion as well, you can start styling components
-  via the `cs` prop or our new styling utilities.
 
 ## Table of contents
 
 - [Canvas Tokens](#canvas-tokens)
 - [Codemod](#codemod)
+  - [Instructions](#instructions)
+- [Styling Updates](#styling-updates)
+  - [Compatibility Mode](#compatibility-mode)
 - [Deprecations](#deprecations)
+  - [Form Field Container](#form-field-container)
 - [Removals](#removals)
-  - [InputIconContainer](#inputiconcontainer)
-  - [Select (Preview)](#select-preview)
+  - [Input Icon Container](#input-icon-container)
 - [Component Updates](#component-updates)
   - [Styling API and CSS Tokens](#styling-api-and-css-tokens)
   - [Avatar](#avatar)
+  - [Form Field](#form-field)
+    - [Form Field Group](#form-field-group)
+    - [Form Field Field](#form-field-field)
+  - [Search Form](#search-form)
+  - [Select](#select)
   - [Text Area](#text-area)
 - [Troubleshooting](#troubleshooting)
 - [Glossary](#glossary)
@@ -55,30 +57,124 @@ A note to the reader:
 
 In v12, all the components listed in this guide have started using our new
 [Canvas Tokens Web](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
-
-In v12 you must add `@workday/canvas-tokens-web` to ensure our components are properly styled and
-the variables are defined. For more information on installing and using, please reference our tokens
+**You must** add `@workday/canvas-tokens-web` to ensure our components are properly styled and the
+variables are defined. For more information on installing and using, please reference our tokens
 [docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
 
+## Codemod
+
+We've provided a [codemod](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) to
+automatically update your code to work with most of the breaking changes in v12. **Breaking changes
+handled by the codemod are marked with 🤖 in the Upgrade Guide.**
+
+> **Note: In v12, we have done some infrastructure updates with moving to Storybook 7, Webpack 5,
+> Typescript 4.9 and Cypress 13 . With these updates has come some formatting issues after running
+> our codemods. We recommend running a formatter to address the format issues that have been
+> introduced in v12.**
+
+A codemod is a script that makes programmatic transformations on your codebase by traversing the
+[AST](https://www.codeshiftcommunity.com/docs/understanding-asts), identifying patterns, and making
+prescribed changes. This greatly decreases opportunities for error and reduces the number of manual
+updates, which allows you to focus on changes that need your attention. **We highly recommend you
+use the codemod for these reasons.**
+
+If you're new to running codemods or if it's been a minute since you've used one, there are a few
+things you'll want to keep in mind.
+
+- Our codemods are meant to be run sequentially. For example, if you're using v8 of Canvas Kit,
+  you'll need to run the v9 codemod before you run v10 and so on.
+- The codemod will update your code to be compatible with the specified version, but it will **not**
+  remove outdated dependencies or upgrade dependencies to the latest version. You'll need to upgrade
+  dependencies on your own.
+  - We recommend upgrading dependencies before running the codemod.
+  - Always review your `package.json` files to make sure your dependency versions look correct.
+- The codemod will not handle every breaking change in v12. You will likely need to make some manual
+  changes to be compatible. Use our Upgrade Guide as a checklist.
+- Codemods are not bulletproof.
+  - Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
+  - As a safety precaution, we recommend committing the changes from the codemod as a single
+    isolated commit (separate from other changes) so you can roll back more easily if necessary.
+
+We're here to help! Automatic changes to your codebase can feel scary. You can always reach out to
+our team. We'd be very happy to walk you through the process to set you up for success.
+
+### Instructions
+
+The easiest way to run our codemod is to use `npx` in your terminal.
+
+```sh
+npx @workday/canvas-kit-codemod v12 [path]
+```
+
+Be sure to provide specific directories that need to be updated via the `[path]` argument. This
+decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
+having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
+if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
+`[path]`.
+
+Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
+codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
+finished.
+
+```sh
+yarn add @workday/canvas-kit-codemod --dev
+yarn canvas-kit-codemod v12 [path]
+yarn remove @workday/canvas-kit-codemod
+```
+
+> **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
+> manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
+> after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
+> your project conventions.
+
+## Styling Updates
+
+### Compatibility Mode
+
+In v12, we have addressed a style merge issue with removing forced compatibility mode. For more
+information on this change, please read our
+[discussion](https://github.com/Workday/canvas-kit/discussions/2893).
+
 ## Deprecations
 
 We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
 in a future major release. This signals consumers to migrate to a more stable alternative before the
 deprecated code is removed.
 
-## Removals
+### Form Field Container
 
-Removals are deletions from our codebase and you can no longer consume this component. We've either
-promoted or replaced a component or utility.
+**PR:** [#2865](https://github.com/Workday/canvas-kit/pull/2865)
 
-### Select (Preview)
+We've deprecated `FormField.Container` in v12. Please use `FormField.Field` or
+`FormFieldGroup.Field` for grouped inputs as this ensures proper label alignment and spacing of
+inputs and hint text, regardless of the orientation.
 
-**PR:** [#2796](https://github.com/Workday/canvas-kit/pull/2796)
+```tsx
+// v11
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Container>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>You must provide an email</FormField.Hint>
+  </FormField.Container>
+</FormField>
+
+// v12
+<FormField>
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>You must provide an email</FormField.Hint>
+  </FormField.Field>
+</FormField>
+```
 
-We've removed the `Select` component that was in Preview. Please use the compound
-[Select component from Main](https://workday.github.io/canvas-kit/?path=/docs/components-inputs-select--basic).
+## Removals
 
-### InputIconContainer
+Removals are deletions from our codebase and you can no longer consume this component. We've either
+promoted or replaced a component or utility.
+
+### Input Icon Container
 
 **PR:** [#2838](https://github.com/Workday/canvas-kit/pull/2838)
 
@@ -92,15 +188,21 @@ from Main instead.
 
 ### Styling API and CSS Tokens
 
-**PRs:** [#2825](https://github.com/Workday/canvas-kit/pull/2825),
+**PRs:** [#2793](https://github.com/Workday/canvas-kit/pull/2793),
+[#2865](https://github.com/Workday/canvas-kit/pull/2865),
+[#2881](https://github.com/Workday/canvas-kit/pull/2881),
+[#2825](https://github.com/Workday/canvas-kit/pull/2825),
 [#2795](https://github.com/Workday/canvas-kit/pull/2795),
-[#2793](https://github.com/Workday/canvas-kit/pull/2793)
 
 Several components have been refactored to use our new
 [Canvas Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) and
 [styling API](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-modifiers#createstyles-api).
 The React interface **has not changed**, but CSS variables are now used for dynamic properties.
 
+> **Note:** These components also support our new `cs` prop for styling. Learn more about styling
+> with `cs` in our
+> [documentation](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--cs-prop).
+
 The following components are affected:
 
 - `Avatar`
@@ -111,18 +213,222 @@ The following components are affected:
 - `TextInput`
 - `Toast`
 
-> **Note:** These components also support our new `cs` prop for styling. Learn more about styling
-> with `cs` in our
-> [documentation](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--cs-prop).
-
 ### Avatar
 
-- Avatar no longer uses `SystemIconCircle` for sizing.
-- `Avatar.Size` is no longer supported. The `size` prop type has change to accept the following:
+**PR** [#2793](https://github.com/Workday/canvas-kit/pull/2793)
+
+Avatar has been updated to use our new
+[styling utilities](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-stencil).
+The following changes have been made to the API:
+
+- `Avatar.Size` has been deprecated. The `size` prop still accepts `Avatar.Size` in addition to the
+  following values:
   `"extraExtraLarge" | "extraLarge" | "large" | "medium" | "small" | "extraSmall" | (string{})`
-- `Avatar.Variant` is no longer supported. Enum `AvatarVariant` has been removed. The `variant` type
-  prop now accepts `"dark" | "light"`
-- The `as` prop now accepts any element, not just `div`.
+- `Avatar.Variant` has been deprecated. The `variant` prop still accepts `Avatar.Variant` in
+  addition to the following values: `"dark" | "light"`
+- The `as` prop now accepts any element, not just a `div`.
+
+> **Note:** Both `Avatar.Size` and `Avatar.Variant` have been deprecated in favor of the new string
+> union types. You will see a console warn message while in development if you're still using this.
+> Please update your types and usage before v13.
+
+### Form Field
+
+<div style={{display: 'inline-flex', gap: '.5rem'}}>
+  <StatusIndicator variant="red" emphasis="low">
+    <StatusIndicator.Label>Breaking Change</StatusIndicator.Label>
+  </StatusIndicator>
+  <StatusIndicator variant="green" emphasis="low">
+    <StatusIndicator.Label>🤖 Codemod Available</StatusIndicator.Label>
+  </StatusIndicator>
+</div>
+
+**PRs:** [#2865](https://github.com/Workday/canvas-kit/pull/2865),
+[#2881](https://github.com/Workday/canvas-kit/pull/2881),
+[#2934](https://github.com/Workday/canvas-kit/pull/2934)
+
+We've promoted FormField from [Preview](#preview) to [Main](#main). The following changes has been
+made to provide more flexibility and better explicit components when using inputs.
+
+- The orientation prop on the `FormField` component will be updated to accept the following values:
+  `"vertical"`, `"horizontalStart"`, and `"horizontalEnd"`. `"horizontal"` will still be accepted as
+  a value in v12, but it will be deprecated and slated for removal in a future major release. These
+  changes are intended to provide more flexibility with label alignments on `FormField` elements.
+
+> **Note**: The horizontal alignment of start and end are relative to its container, meaning start
+> and end match the flex property of `flex-start` and `flex-end`. This is especially applicable for
+> moving between RTL (right-to-left) and LTR (left-to-right) languages.
+
+> **Note:** Orientation `"horizontal"` has been deprecated. You will see a console warn message
+> suggesting to update your types and usage to `"horizontalStart"`, `"horizontalEnd"` or
+> `"vertical"`.
+
+- `useFormFieldModel`: `orientation` has been added back into `useFormFieldModel`. While we still
+  support compat mode due to
+  [style merging issues](https://github.com/Workday/canvas-kit/discussions/2893), having orientation
+  on the model allows for proper styling of sub components.
+
+- Styles clean up: `FormField.Hint` and `FormField.Label` where using `margin` for spacing. We've
+  updated styles so that the containing element uses `gap` for proper spacing.
+
+- We've added a new
+  [example](https://workday.github.io/canvas-kit/?path=/docs/examples-forms-density-and-alignment--docs)
+  to our docs to showcase how our inputs can be styled in different environments like density and
+  container alignment.
+
+> **Note:** If spacing seems off between the input and hint text, ensure you're using
+> `FormField.Field` wrapping your input and hint text.
+
+##### Breaking API Change
+
+The newly promoted `FormField` is a
+[compound component](https://workday.github.io/canvas-kit/?path=/docs/guides-compound-components--page).
+Due to the different APIs of the component, this change is **not codemodable**. The following shows
+an example of how to **update** your code to match the new compound component API.
+
+```tsx
+// v11 FormField in Main
+<FormField
+  error={FormField.ErrorType.Alert}
+  labelPosition={FormField.LabelPosition.Left}
+  useFieldSet={true}
+  required={true}
+  hintId="hint-alert"
+  hintText="Please enter a valid email."
+  label="Email"
+>
+  <TextInput onChange={handleChange} value={value} />
+</FormField>
+
+
+// v12 Newly promoted FormField from Preview to Main
+<FormField
+  error="error"
+  orientation="horizontalStart"
+  isRequired={true}
+>
+	<FormField.Label>Email</FormField.Label>
+	<FormField.Field>
+		<FormField.Input as={TextInput} onChange={handleChange} value={value} />
+		<FormField.Hint>Please enter a valid email.</FormField.Hint>
+	</FormField.Field>
+</FormField>
+```
+
+**Noticeable changes:**
+
+- `error` prop takes in the following values: `"error" | "alert"`.
+- `labelPosition` becomes `orientation` with the following values:
+  `"horizontal" | "horizontalStart" | "horizontalEnd" | "vertical"`.
+- `useFieldSet` is no longer valid. If you want to group inputs, use
+  [`FormFieldGroup`](#form-field-group) component.
+- `required` becomes `isRequired`.
+- `hintId` is no longer needed. The component handles associating the hint text, label and input
+  automatically. If you wish to have a unique `id`, you can add one onto the `FormField` element.
+- `hintText` is no longer a valid prop. Use `FormField.Hint` sub-component.
+- `errorLabel` and `alertLabel` are no longer valid props. Customize your hint text inside of
+  `FormField.Hint`.
+- `label` is no longer a valid prop. Use `FormField.Label` sub component to render your label text.
+- Instead of rendering an input, ensure you use `FormField.Input` with the `as` prop. This ensures
+  proper error handling and aria attributes for accessibility.
+
+🤖 The codemod will handle the change of `orientation="horizontal"` to
+`orientation="horizontalStart"` if you're using the string literal values. It will also handle
+updating your imports from `@workday/canvas-kit-preview-react/form-field` to
+`@workday/canvas-kit-react/form-field`.
+
+#### Form Field Group
+
+We've added a new component to the `FormField` package to allow users to group inputs without
+worrying about setting the `as` prop on the `FormField` component.
+
+Use `FormFieldGroup` when you have a group of inputs that need to be associated to one another, like
+`RadioGroup` or a group of `Checkbox`'s.
+
+`FormFieldGroup` supports the same props of `FormField`:
+
+- `error`: `"alert" | "error"` Defines the error around the whole group of inputs.
+- `orientation`: `"horizontalStart" | "horizontalEnd" | "vertical" | "horizontal" `. Defines the
+  label placement.
+- `isRequired`: `true` Defines if a group like `RadioGroup` is required.
+
+#### Form Field Field
+
+We've added a new sub-component to `FormField` and `FormFieldGroup`, `FormField.Field` and
+`FormFieldGroup.Field`. This sub-component is meant to ensure that the label is always aligned with
+the input regardless of the `orientation`prop's value on`FormField` or `FormFieldGroup`. This
+component should replace `FormField.Container` and always be used to ensure proper alignment of the
+label and hint text. Our examples have been updated to reflect this.
+
+Although there is no codemod for this change and it's non-breaking, we suggest moving towards adding
+this sub-component when using `FormField`. This component also exists on `FormFieldGroup`.
+
+```tsx
+<FormField orientation="horizontal">
+  <FormField.Label>Email</FormField.Label>
+  <FormField.Field>
+    <FormField.Input as={TextInput} />
+    <FormField.Hint>You must provide an email</FormField.Hint>
+  </FormField.Field>
+</FormField>
+```
+
+### Search Form (Labs)
+
+**PRs:** [#2934](https://github.com/Workday/canvas-kit/pull/2934),
+
+`SearchForm` is now using the newly promoted `FormField` component. `SearchForm` now uses `labelId`
+to set the appropiate aria attributes and `id` on the underlying input element. There should be no
+visual breaking changes and the API remains the same.
+
+### Select
+
+**PR:** [#2865](https://github.com/Workday/canvas-kit/pull/2865)
+
+As we transition to use our CSS tokens to provide better theming capabilities and our new styling
+methods, we're moving away from components extending `Themeable`. `Themeable` has been removed from
+`SelectProps.`
+
+If you wish to theme `Select` we suggest using the `CanvasProvider` to do so.
+
+```tsx
+const theme: PartialEmotionCanvasTheme = {
+  canvas: {
+    palette: {
+      common: {
+        focusOutline: 'pink',
+      },
+      primary: {
+        main: 'green',
+        light: 'lightgreen',
+      },
+    },
+  },
+};
+
+//...
+
+<CanvasProvider theme={theme}>
+  <Flex cs={parentContainerStyles}>
+    <Select items={options}>
+      <FormField>
+        <FormField.Label>Contact</FormField.Label>
+        <FormField.Input as={Select.Input} onChange={handleChange} />
+        <Select.Popper>
+          <Select.Card>
+            <Select.List>
+              {item => {
+                return <Select.Item>{item}</Select.Item>;
+              }}
+            </Select.List>
+          </Select.Card>
+        </Select.Popper>
+      </FormField>
+    </Select>
+    Selected Value: {value}
+  </Flex>
+</CanvasProvider>;
+```
 
 ### Text Area
 
@@ -134,17 +440,22 @@ type.
 
 ```tsx
 // v11
-interface MyProps { resize?: TextAreaResizeDirection }
-
-// 12 type ValueOf<T> = T[keyof T]; interface MyProps { resize?:
-ValueOf<typeof TextAreaResizeDirection> }
+interface MyProps {
+  resize?: TextAreaResizeDirection;
+}
+
+// v12
+type ValueOf<T> = T[keyof T];
+interface MyProps {
+  resize?: ValueOf<typeof TextAreaResizeDirection>;
+}
 ```
 
 ## Troubleshooting
 
 ### My Styles Seem Broken?
 
-Our components are reliant on our new Canvas Tokens Web package. Be sure you install
+Our components are reliant on our new Canvas Tokens Web package. Be sure to install
 `@workday/canvas-tokens-web`. For more information, reference our
 [Getting Started docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)
 for this package.
@@ -201,5 +512,5 @@ experimental code and is analagous to code in alpha.
 
 Breaking changes can be deployed to Labs at any time without triggering a major version update and
 may not be subject to the same rigor in communcation and migration strategies reserved for breaking
-changes in [Preview](#preview) and [Main](#main). import { opacity } from
-"@workday/canvas-tokens-web/dist/es6/system"
+changes in [Preview](#preview) and [Main](#main).
+`import { opacity } from "@workday/canvas-tokens-web/dist/es6/system"`

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

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Upgrade Guides/v4.0"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Canvas Kit 4.0 Upgrade Guide
 
 Below are the breaking changes made in Canvas Kit v4. Please reach out if you have any questions
@@ -40,7 +30,7 @@ our React infrastructure and components.
 Breaking:
 
 - React & ReactDOM upgraded to 16.12 (https://github.com/Workday/canvas-kit/pull/533)
-  - We are now fully adopting hooks, so <= 16.7 is no longer supported
+  - We are now fully adopting hooks, so version 16.7 and below are no longer supported
 
 Non-breaking:
 

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

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Upgrade Guides/v5.0"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Canvas Kit 5.0 Upgrade Guide
 
 Below are the breaking changes made in Canvas Kit v5. Please

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

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Upgrade Guides/v6.0"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Canvas Kit 6.0 Upgrade Guide
 
 Below are the breaking changes made in Canvas Kit v6. Please

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

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Upgrade Guides/v7.0"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Canvas Kit 7.0 Upgrade Guide
 
 This guide contains breaking changes in Canvas Kit v7. Please

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

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Upgrade Guides/v8.0"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Canvas Kit 8.0 Upgrade Guide
 
 This guide contains an overview of the changes in Canvas Kit v8. Please

package/dist/mdx/API_PATTERN_GUIDELINES.mdx

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/API & Pattern Guidelines"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: { hidden: true }
-     },
-  }}
-/>
-
 # API & Pattern Guidelines
 
 Note: This repo hasn't seen a full audit, so you may find examples that contradict these guidelines.

package/dist/mdx/COMPOUND_COMPONENTS.mdx

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Compound Components"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Compound Components
 
 ## What is a compound component?

package/dist/mdx/CONTRIBUTING.mdx

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Contributing"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Contributing to Canvas
 
 On behalf of the Canvas team, thank you so much for your contribution to this project and being a

package/dist/mdx/CREATING_COMPOUND_COMPONENTS.mdx

@@ -1,13 +1,3 @@
-<Meta
-  title="Guides/Creating Compound Components"
-  parameters={{
-    viewMode: 'docs',
-    previewTabs: {
-      canvas: {hidden: true},
-    },
-  }}
-/>
-
 # Building a Compound Component
 
 Refer to the