Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Upgrade Guide Cleanup #2936

Merged
merged 2 commits into from
Sep 26, 2024
Merged

chore: Upgrade Guide Cleanup #2936

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da899ff
chore: Reviewed and Updated Upgrade Guide
josh-bagwell Sep 25, 2024
c65061a
chore: Updated Upgrade Guide
josh-bagwell Sep 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 80 additions & 22 deletions modules/docs/mdx/12.0-UPGRADE-GUIDE.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,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
josh-bagwell marked this conversation as resolved.
Show resolved Hide resolved
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)
Expand All @@ -25,31 +25,28 @@ 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)
- [Compatability Mode](#compatability-mode)
- [Compatibility Mode](#compatibility-mode)
- [Deprecations](#deprecations)
- [Form Field Container](#form-field-container)
- [Removals](#removals)
- [InputIconContainer](#inputiconcontainer)
- [Input Icon Container](#input-icon-container)
- [Component Updates](#component-updates)
- [Styling API and CSS Tokens](#styling-api-and-css-tokens)
- [Avatar](#avatar)
- [Select](#select)
- [Form Field](#form-field)
- [Form Field Group](#form-field-group)
- [Form Field Field](#form-field-field)
- [Text Area](#text-area)
- [Troubleshooting](#troubleshooting)
- [Glossary](#glossary)
Expand All @@ -68,13 +65,72 @@ the variables are defined. For more information on installing and using, please

## Codemod

In v12, we have done some infrastructure updates with moving to Webpack 5 and Storybook 7. With
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.
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

### Compatability Mode
### 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).

Expand All @@ -88,8 +144,8 @@ deprecated code is removed.

**PR:** [#2865](https://github.com/Workday/canvas-kit/pull/2865)

We've deprecated `FormField.Container`. Please use `FormField.Field` or `FormFieldGroup.Field` for
grouped inputs, this ensures proper label alignment and spacing of inputs and hint text, regardless
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.

```tsx
Expand Down Expand Up @@ -117,7 +173,7 @@ of the orientation.
Removals are deletions from our codebase and you can no longer consume this component. We've either
promoted or replaced a component or utility.

### InputIconContainer
### Input Icon Container

**PR:** [#2838](https://github.com/Workday/canvas-kit/pull/2838)

Expand All @@ -131,10 +187,12 @@ from Main instead.

### Styling API and CSS Tokens

**PRs:** [#2825](https://github.com/Workday/canvas-kit/pull/2825),
[#2795](https://github.com/Workday/canvas-kit/pull/2795),
**PRs:**
[#2793](https://github.com/Workday/canvas-kit/pull/2793),
[#2881](https://github.com/Workday/canvas-kit/pull/2881)
[#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),

Several components have been refactored to use our new
[Canvas Tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) and
Expand Down Expand Up @@ -223,7 +281,7 @@ Use `FormFieldGroup` when you have a group of inputs that need to be associated
label placement.
- `isRequired`: `true` Defines if a group like `RadioGroup` is required.

#### FormField Field
#### 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
Expand Down Expand Up @@ -307,7 +365,7 @@ interface MyProps {
resize?: TextAreaResizeDirection;
}

// 12
// v12
type ValueOf<T> = T[keyof T];
interface MyProps {
resize?: ValueOf<typeof TextAreaResizeDirection>;
Expand All @@ -318,7 +376,7 @@ interface MyProps {

### 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.
Expand Down
Loading