@workday/canvas-kit-docs 13.0.4 → 14.0.0-alpha.1123-next.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/es6/lib/docs.js +10634 -1134
- package/dist/mdx/14.0-UPGRADE-GUIDE.mdx +106 -0
- package/dist/mdx/PACKAGES.mdx +46 -0
- package/package.json +6 -6
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Canvas Kit 14.0 Upgrade Guide
|
|
2
|
+
|
|
3
|
+
This guide contains an overview of the changes in Canvas Kit v14. Please
|
|
4
|
+
[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
|
|
5
|
+
any questions.
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## Table of contents
|
|
9
|
+
|
|
10
|
+
- [Codemod](#codemod)
|
|
11
|
+
- [Instructions](#instructions)
|
|
12
|
+
- [Component Updates](#component-updates)
|
|
13
|
+
- [Styling API and CSS Tokens](#styling-api-and-css-tokens)
|
|
14
|
+
- [Troubleshooting](#troubleshooting)
|
|
15
|
+
- [Glossary](#glossary)
|
|
16
|
+
- [Main](#main)
|
|
17
|
+
- [Preview](#preview)
|
|
18
|
+
- [Labs](#labs)
|
|
19
|
+
|
|
20
|
+
## Codemod
|
|
21
|
+
|
|
22
|
+
We've provided a [codemod](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) to
|
|
23
|
+
automatically update your code to work with most of the breaking changes in v14. **Breaking changes
|
|
24
|
+
handled by the codemod are marked with 🤖 in the Upgrade Guide.**
|
|
25
|
+
|
|
26
|
+
A codemod is a script that makes programmatic transformations on your codebase by traversing the
|
|
27
|
+
[AST](https://www.codeshiftcommunity.com/docs/understanding-asts), identifying patterns, and making
|
|
28
|
+
prescribed changes. This greatly decreases opportunities for error and reduces the number of manual
|
|
29
|
+
updates, which allows you to focus on changes that need your attention. **We highly recommend you
|
|
30
|
+
use the codemod for these reasons.**
|
|
31
|
+
|
|
32
|
+
If you're new to running codemods or if it's been a minute since you've used one, there are a few
|
|
33
|
+
things you'll want to keep in mind.
|
|
34
|
+
|
|
35
|
+
- Our codemods are meant to be run sequentially. For example, if you're using v8 of Canvas Kit,
|
|
36
|
+
you'll need to run the v9 codemod before you run v10 and so on.
|
|
37
|
+
- The codemod will update your code to be compatible with the specified version, but it will **not**
|
|
38
|
+
remove outdated dependencies or upgrade dependencies to the latest version. You'll need to upgrade
|
|
39
|
+
dependencies on your own.
|
|
40
|
+
- We recommend upgrading dependencies before running the codemod.
|
|
41
|
+
- Always review your `package.json` files to make sure your dependency versions look correct.
|
|
42
|
+
- The codemod will not handle every breaking change in v14. You will likely need to make some manual
|
|
43
|
+
changes to be compatible. Use our Upgrade Guide as a checklist.
|
|
44
|
+
- Codemods are not bulletproof.
|
|
45
|
+
- Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
|
|
46
|
+
- As a safety precaution, we recommend committing the changes from the codemod as a single
|
|
47
|
+
isolated commit (separate from other changes) so you can roll back more easily if necessary.
|
|
48
|
+
|
|
49
|
+
We're here to help! Automatic changes to your codebase can feel scary. You can always reach out to
|
|
50
|
+
our team. We'd be very happy to walk you through the process to set you up for success.
|
|
51
|
+
|
|
52
|
+
### Instructions
|
|
53
|
+
|
|
54
|
+
The easiest way to run our codemod is to use `npx` in your terminal.
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
npx @workday/canvas-kit-codemod v14 [path]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Be sure to provide specific directories that need to be updated via the `[path]` argument. This
|
|
61
|
+
decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
|
|
62
|
+
having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
|
|
63
|
+
if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
|
|
64
|
+
`[path]`.
|
|
65
|
+
|
|
66
|
+
Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
|
|
67
|
+
codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
|
|
68
|
+
finished.
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
yarn add @workday/canvas-kit-codemod --dev
|
|
72
|
+
yarn canvas-kit-codemod v14 [path]
|
|
73
|
+
yarn remove @workday/canvas-kit-codemod
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
> **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
|
|
77
|
+
> manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
|
|
78
|
+
> after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
|
|
79
|
+
> your project conventions.
|
|
80
|
+
|
|
81
|
+
## Styling API and Canvas Tokens 💅
|
|
82
|
+
Several components have been refactored to use our Canvas tokens and styling API. The React interface has not changed, but Canvas Tokens are now used for dynamic properties.
|
|
83
|
+
|
|
84
|
+
> **Note:** These components also support our cs prop for styling. Learn more about styling with cs in our documentation.
|
|
85
|
+
|
|
86
|
+
The following components have been updated:
|
|
87
|
+
|
|
88
|
+
- `Breadcrumbs` [#3270](https://github.com/Workday/canvas-kit/pull/3270)
|
|
89
|
+
|
|
90
|
+
## Troubleshooting
|
|
91
|
+
|
|
92
|
+
- When upgrading to the latest major version of Canvas Kit, all related Canvas Kit packages should
|
|
93
|
+
be updated at the same time:
|
|
94
|
+
- `"@workday/canvas-kit-react": "^12.5.6"` -> `"@workday/canvas-kit-react": "^13.0.0"`
|
|
95
|
+
- `"@workday/canvas-kit-styling": "^12.5.6"` -> `"@workday/canvas-kit-styling": "^13.0.0"`
|
|
96
|
+
- `"@workday/canvas-kit-preview-react": "^12.5.6"` ->
|
|
97
|
+
`"@workday/canvas-kit-preview-react": "^13.0.0"`
|
|
98
|
+
- `"@workday/canvas-kit-labs-react": "^12.5.6"` -> `"@workday/canvas-kit-labs-react": "^13.0.0"`
|
|
99
|
+
- Our components rely on the `@workday/canvas-tokens-web` package which provides our CSS variables
|
|
100
|
+
and ensures the correct styling of our components. Make sure to upgrade to the latest version of
|
|
101
|
+
Canvas Tokens Web and install it correctly. For more information,
|
|
102
|
+
[view our docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
|
|
103
|
+
|
|
104
|
+
## Glossary
|
|
105
|
+
|
|
106
|
+
For an overview of the different packages we provide, plase view our docs [here](https://workday.github.io/canvas-kit/?path=/docs/guides-packages--docs).
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
### Main
|
|
2
|
+
|
|
3
|
+
Our Main package of Canvas Kit components and utilities at `@workday/canvas-kit-react` has
|
|
4
|
+
undergone a full design and a11y review and is approved for use in product.
|
|
5
|
+
|
|
6
|
+
Breaking changes to code in Main will only occur during major version updates and will always be
|
|
7
|
+
communicated in advance and accompanied by migration strategies.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
### Preview
|
|
12
|
+
|
|
13
|
+
Our Preview package of Canvas Kit components and utilities at
|
|
14
|
+
`@workday/canvas-kit-preview-react` has undergone a full design and a11y review and is approved for
|
|
15
|
+
use in product, but may not be up to the high code standards upheld in the [Main](#main) package.
|
|
16
|
+
Preview is analagous to code in beta.
|
|
17
|
+
|
|
18
|
+
Breaking changes are unlikely, but possible, and can be deployed to Preview at any time without
|
|
19
|
+
triggering a major version update, though such changes will be communicated in advance and
|
|
20
|
+
accompanied by migration strategies.
|
|
21
|
+
|
|
22
|
+
Generally speaking, our goal is to eventually promote code from Preview to [Main](#main).
|
|
23
|
+
Occasionally, a component with the same name will exist in both [Main](#main) and Preview (for
|
|
24
|
+
example, see Segmented Control in [Preview](/components/buttons/segmented-control/) and
|
|
25
|
+
[Main](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/components-buttons-segmented-control--basic)).
|
|
26
|
+
In these cases, Preview serves as a staging ground for an improved version of the component with a
|
|
27
|
+
different API. The component in [Main](#main) will eventually be replaced with the one in Preview.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
### Labs
|
|
32
|
+
|
|
33
|
+
Our Labs package of Canvas Kit components and utilities at `@workday/canvas-kit-labs-react`
|
|
34
|
+
has **not** undergone a full design and a11y review. Labs serves as an incubator space for new and
|
|
35
|
+
experimental code and is analagous to code in alpha.
|
|
36
|
+
|
|
37
|
+
Breaking changes can be deployed to Labs at any time without triggering a major version update and
|
|
38
|
+
may not be subject to the same rigor in communcation and migration strategies reserved for breaking
|
|
39
|
+
changes in [Preview](#preview) and [Main](#main).
|
|
40
|
+
`import { opacity } from "@workday/canvas-tokens-web/dist/es6/system"`
|
|
41
|
+
|
|
42
|
+
### Styling
|
|
43
|
+
|
|
44
|
+
This package contains everything needed to create CSS styling. This styling package contains a
|
|
45
|
+
runtime for development and a static parsing process for build time. For more information, visit
|
|
46
|
+
https://workday.github.io/canvas-kit/?path=/docs/styling-why-canvas-styling--docs
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workday/canvas-kit-docs",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "14.0.0-alpha.1123-next.0",
|
|
4
4
|
"description": "Documentation components of Canvas Kit components",
|
|
5
5
|
"author": "Workday, Inc. (https://www.workday.com)",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -45,10 +45,10 @@
|
|
|
45
45
|
"@emotion/styled": "^11.6.0",
|
|
46
46
|
"@stackblitz/sdk": "^1.11.0",
|
|
47
47
|
"@storybook/csf": "0.0.1",
|
|
48
|
-
"@workday/canvas-kit-labs-react": "^
|
|
49
|
-
"@workday/canvas-kit-preview-react": "^
|
|
50
|
-
"@workday/canvas-kit-react": "^
|
|
51
|
-
"@workday/canvas-kit-styling": "^
|
|
48
|
+
"@workday/canvas-kit-labs-react": "^14.0.0-alpha.1123-next.0",
|
|
49
|
+
"@workday/canvas-kit-preview-react": "^14.0.0-alpha.1123-next.0",
|
|
50
|
+
"@workday/canvas-kit-react": "^14.0.0-alpha.1123-next.0",
|
|
51
|
+
"@workday/canvas-kit-styling": "^14.0.0-alpha.1123-next.0",
|
|
52
52
|
"@workday/canvas-system-icons-web": "^3.0.0",
|
|
53
53
|
"@workday/canvas-tokens-web": "^2.1.1",
|
|
54
54
|
"markdown-to-jsx": "^7.2.0",
|
|
@@ -61,5 +61,5 @@
|
|
|
61
61
|
"mkdirp": "^1.0.3",
|
|
62
62
|
"typescript": "5.0"
|
|
63
63
|
},
|
|
64
|
-
"gitHead": "
|
|
64
|
+
"gitHead": "3601377207d7646ceeffe3a2161b671ccd8e8eab"
|
|
65
65
|
}
|