@workday/canvas-kit-mcp 15.0.0-alpha.0008-next.0 → 15.0.0-alpha.0023-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/cli.js +4 -3
- package/dist/cli.js.map +3 -3
- package/dist/index.js +4 -3
- package/dist/index.js.map +3 -3
- package/dist/lib/upgrade-guides/15.0-UPGRADE-GUIDE.md +293 -0
- package/package.json +2 -2
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
# Canvas Kit 15.0 Upgrade Guide
|
|
2
|
+
|
|
3
|
+
This guide contains an overview of the changes in Canvas Kit v15. 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
|
+
## Why You Should Upgrade
|
|
8
|
+
|
|
9
|
+
v15.0 and v4.0 Canvas Tokens Web introduces new shape, size, gap, and padding tokens to our components. While we still support our old shape and
|
|
10
|
+
space tokens, the new tokens aim to add more semantic meaning to allow for better use and theming.
|
|
11
|
+
|
|
12
|
+
> **Note:** While v15 and v4 tokens should be backwards compatible with previous versions that use
|
|
13
|
+
> CSS tokens, we strongly advise to migrate both Canvas Kit and Canvas Tokens Web together.
|
|
14
|
+
|
|
15
|
+
## Table of Contents
|
|
16
|
+
|
|
17
|
+
- [Codemod](#codemod)
|
|
18
|
+
- [Instructions](#instructions)
|
|
19
|
+
- [Component Promotions](#component-promotions)
|
|
20
|
+
- [Segmented Control](#segmented-control-)
|
|
21
|
+
- [Component Updates](#component-updates)
|
|
22
|
+
- [Buttons](#buttons)
|
|
23
|
+
- [Removals](#removals)
|
|
24
|
+
- [Segmented Control (Deprecated)](#segmented-control-deprecated)
|
|
25
|
+
- [Glossary](#glossary)
|
|
26
|
+
- [Main](#main)
|
|
27
|
+
- [Preview](#preview)
|
|
28
|
+
|
|
29
|
+
## Codemod
|
|
30
|
+
|
|
31
|
+
We've provided a [codemod](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) to
|
|
32
|
+
automatically update your code to work with most of the breaking changes in v15. **Breaking changes
|
|
33
|
+
handled by the codemod are marked with 🤖 in the Upgrade Guide.**
|
|
34
|
+
|
|
35
|
+
A codemod is a script that makes programmatic transformations on your codebase by traversing the
|
|
36
|
+
AST, identifying patterns, and making prescribed changes. This greatly decreases opportunities for
|
|
37
|
+
error and reduces the number of manual updates, which allows you to focus on changes that need your
|
|
38
|
+
attention. **We highly recommend you use the codemod for these reasons.**
|
|
39
|
+
|
|
40
|
+
If you're new to running codemods or if it's been a minute since you've used one, there are a few
|
|
41
|
+
things you'll want to keep in mind.
|
|
42
|
+
|
|
43
|
+
- Our codemods are meant to be run sequentially. For example, if you're using v13 of Canvas Kit,
|
|
44
|
+
you'll need to run the v14 codemod before you run v15.
|
|
45
|
+
- The codemod will update your code to be compatible with the specified version, but it will **not**
|
|
46
|
+
remove outdated dependencies or upgrade dependencies to the latest version. You'll need to upgrade
|
|
47
|
+
dependencies on your own.
|
|
48
|
+
- We recommend upgrading dependencies before running the codemod.
|
|
49
|
+
- Always review your `package.json` files to make sure your dependency versions look correct.
|
|
50
|
+
- The codemod will not handle every breaking change in v15. You will likely need to make some manual
|
|
51
|
+
changes to be compatible. Use our Upgrade Guide as a checklist.
|
|
52
|
+
- Codemods are not bulletproof.
|
|
53
|
+
- Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
|
|
54
|
+
- As a safety precaution, we recommend committing the changes from the codemod as a single
|
|
55
|
+
isolated commit (separate from other changes) so you can roll back more easily if necessary.
|
|
56
|
+
|
|
57
|
+
We're here to help! Automatic changes to your codebase can feel scary. You can always reach out to
|
|
58
|
+
our team. We'd be very happy to walk you through the process to set you up for success.
|
|
59
|
+
|
|
60
|
+
### Instructions
|
|
61
|
+
|
|
62
|
+
The easiest way to run our codemod is to use `npx` in your terminal.```sh
|
|
63
|
+
npx @workday/canvas-kit-codemod v15 [path]
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Be sure to provide specific directories that need to be updated via the `[path]` argument. This
|
|
67
|
+
decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
|
|
68
|
+
having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
|
|
69
|
+
if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
|
|
70
|
+
`[path]`.
|
|
71
|
+
|
|
72
|
+
Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
|
|
73
|
+
codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
|
|
74
|
+
finished.
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
yarn add @workday/canvas-kit-codemod --dev
|
|
78
|
+
yarn canvas-kit-codemod v15 [path]
|
|
79
|
+
yarn remove @workday/canvas-kit-codemod
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
> **Note:** The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
|
|
83
|
+
> manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
|
|
84
|
+
> after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
|
|
85
|
+
> your project conventions.
|
|
86
|
+
|
|
87
|
+
## Component Promotions
|
|
88
|
+
|
|
89
|
+
### Segmented Control ⚡️
|
|
90
|
+
|
|
91
|
+
We've promoted `SegmentedControl` from [Preview](/components/buttons/segmented-control/) to [Main](#main). This replaces the deprecated `SegmentedControl` that was previously in Main.
|
|
92
|
+
|
|
93
|
+
**Before in v14**
|
|
94
|
+
|
|
95
|
+
```tsx
|
|
96
|
+
import {SegmentedControl} from '@workday/canvas-kit-preview-react/segmented-control';
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**After in v15**
|
|
100
|
+
|
|
101
|
+
```tsx
|
|
102
|
+
import {SegmentedControl} from '@workday/canvas-kit-react/segmented-control';
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
> 🤖 The codemod will handle the change of imports as shown above.
|
|
106
|
+
|
|
107
|
+
#### API Differences
|
|
108
|
+
|
|
109
|
+
The new `SegmentedControl` is a [compound component](/getting-started/for-developers/resources/compound-components/)
|
|
110
|
+
with a different API than the deprecated version.
|
|
111
|
+
|
|
112
|
+
##### Structure Changes
|
|
113
|
+
|
|
114
|
+
| Deprecated (Old Main) | New (Promoted from Preview) |
|
|
115
|
+
| --------------------- | ----------------------------------- |
|
|
116
|
+
| `SegmentedControl` | `SegmentedControl` |
|
|
117
|
+
| `SegmentedControl.Button` | `SegmentedControl.List` + `SegmentedControl.Item` |
|
|
118
|
+
|
|
119
|
+
##### Prop Changes
|
|
120
|
+
|
|
121
|
+
| Feature | Deprecated (Old Main) | New (Promoted from Preview) |
|
|
122
|
+
| ---------------- | ------------------------------------------ | ------------------------------------------------ |
|
|
123
|
+
| Selection | `value` prop on container | `initialValue` prop on container |
|
|
124
|
+
| Change handler | `onChange={(value) => {}}` | `onSelect={(data) => setSelected(data.id)}` |
|
|
125
|
+
| Item identifier | `value` prop on Button | `data-id` prop on Item |
|
|
126
|
+
| Disabled (all) | Not supported | `disabled` prop on container model |
|
|
127
|
+
| Size | Not supported | `size` prop (`small`, `medium`, `large`) |
|
|
128
|
+
| Orientation | Not supported | `orientation` prop (`horizontal`, `vertical`) |
|
|
129
|
+
| Text labels | Not supported | `children` on Item |
|
|
130
|
+
| Tooltips | Not supported | `tooltipProps` on Item |
|
|
131
|
+
| Accessibility | Manual | Built-in `aria-label` on List |
|
|
132
|
+
|
|
133
|
+
##### Code Migration
|
|
134
|
+
|
|
135
|
+
**Deprecated API (Old Main)**
|
|
136
|
+
|
|
137
|
+
```tsx
|
|
138
|
+
import {SegmentedControl} from '@workday/canvas-kit-react/segmented-control';
|
|
139
|
+
|
|
140
|
+
const [value, setValue] = React.useState<string | number>('list-view');
|
|
141
|
+
|
|
142
|
+
<SegmentedControl value={value} onChange={setValue}>
|
|
143
|
+
<SegmentedControl.Button icon={listViewIcon} value="list-view" />
|
|
144
|
+
<SegmentedControl.Button icon={worksheetsIcon} value="table-view" />
|
|
145
|
+
<SegmentedControl.Button icon={deviceTabletIcon} value="device-view" />
|
|
146
|
+
</SegmentedControl>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
**New API (v15)**
|
|
150
|
+
|
|
151
|
+
```tsx
|
|
152
|
+
import {SegmentedControl} from '@workday/canvas-kit-react/segmented-control';
|
|
153
|
+
|
|
154
|
+
const [value, setValue] = React.useState('list-view');
|
|
155
|
+
|
|
156
|
+
<SegmentedControl initialValue={value} onSelect={data => setValue(data.id)}>
|
|
157
|
+
<SegmentedControl.List aria-label="View type">
|
|
158
|
+
<SegmentedControl.Item data-id="list-view" icon={listViewIcon} tooltipProps={{title: 'List'}} />
|
|
159
|
+
<SegmentedControl.Item data-id="table-view" icon={worksheetsIcon} tooltipProps={{title: 'Table'}} />
|
|
160
|
+
<SegmentedControl.Item data-id="device-view" icon={deviceTabletIcon} tooltipProps={{title: 'Device'}} />
|
|
161
|
+
</SegmentedControl.List>
|
|
162
|
+
</SegmentedControl>
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
##### New Features
|
|
166
|
+
|
|
167
|
+
The promoted `SegmentedControl` includes several new features:
|
|
168
|
+
|
|
169
|
+
- **Text and icon support**: Items can display text, icons, or both
|
|
170
|
+
- **Size variants**: `small`, `medium`, and `large` sizes
|
|
171
|
+
- **Vertical orientation**: Use `orientation="vertical"` for vertical layouts
|
|
172
|
+
- **Built-in tooltips**: Add tooltips via `tooltipProps` on items
|
|
173
|
+
- **Disabled state**: Disable all items via the model or individual items
|
|
174
|
+
- **Dynamic items**: Render items dynamically using the collection API
|
|
175
|
+
|
|
176
|
+
```tsx
|
|
177
|
+
// Text only
|
|
178
|
+
<SegmentedControl.Item data-id="yearly">Yearly</SegmentedControl.Item>
|
|
179
|
+
|
|
180
|
+
// Icon with text
|
|
181
|
+
<SegmentedControl.Item data-id="list" icon={listViewIcon}>List View</SegmentedControl.Item>
|
|
182
|
+
|
|
183
|
+
// With size and orientation
|
|
184
|
+
<SegmentedControl size="large" orientation="vertical">
|
|
185
|
+
...
|
|
186
|
+
</SegmentedControl>
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Component Updates
|
|
190
|
+
|
|
191
|
+
### Buttons
|
|
192
|
+
|
|
193
|
+
**PR:** [#3604](https://github.com/Workday/canvas-kit/pull/3604)
|
|
194
|
+
|
|
195
|
+
The Following components have been updated to use our new `size`, `padding`, `gap` and `shape`
|
|
196
|
+
tokens. These changes are **only visual**.
|
|
197
|
+
|
|
198
|
+
`PrimaryButton`, `SecondaryButton`, `DeleteButton`, `TertiaryButton`, `ToolbarButton`,
|
|
199
|
+
`ToolbarDropdownButton`, `Hyperlink`, `ExternalHyperlink`, and `ActionBar`.
|
|
200
|
+
|
|
201
|
+
## Removals
|
|
202
|
+
|
|
203
|
+
### Segmented Control (Deprecated)
|
|
204
|
+
|
|
205
|
+
The deprecated `SegmentedControl` that was previously in `@workday/canvas-kit-react/segmented-control`
|
|
206
|
+
has been removed. This was the older implementation that used `SegmentedControl.Button` subcomponents.
|
|
207
|
+
|
|
208
|
+
Please migrate to the new `SegmentedControl` component (promoted from Preview) which uses a compound
|
|
209
|
+
component pattern with `SegmentedControl.List` and `SegmentedControl.Item`. See the
|
|
210
|
+
[API Differences](#api-differences) section above for migration guidance.
|
|
211
|
+
|
|
212
|
+
## Glossary
|
|
213
|
+
|
|
214
|
+
For an overview of the different packages we provide, please view our docs
|
|
215
|
+
[here](https://workday.github.io/canvas-kit/?path=/docs/guides-packages--docs).
|
|
216
|
+
|
|
217
|
+
### Main
|
|
218
|
+
|
|
219
|
+
Components in the Main package are stable and ready for production use.
|
|
220
|
+
|
|
221
|
+
### Preview
|
|
222
|
+
|
|
223
|
+
Components in the Preview package are mostly stable but may still receive breaking changes before
|
|
224
|
+
being promoted to Main.
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## Codemod Reference
|
|
229
|
+
|
|
230
|
+
# What is a Codemod?
|
|
231
|
+
|
|
232
|
+
A codemod is a script that makes programmatic transformations on your codebase by traversing the
|
|
233
|
+
[AST](https://www.codeshiftcommunity.com/docs/understanding-asts), identifying patterns, and making
|
|
234
|
+
prescribed changes. This greatly decreases opportunities for error and reduces the number of manual
|
|
235
|
+
updates, which allows you to focus on changes that need your attention. **We highly recommend you
|
|
236
|
+
use the codemod for these reasons.**
|
|
237
|
+
|
|
238
|
+
If you're new to running codemods or if it's been a minute since you've used one, there are a few
|
|
239
|
+
things you'll want to keep in mind.
|
|
240
|
+
|
|
241
|
+
- Our codemods are meant to be run sequentially. For example, if you're using v8 of Canvas Kit,
|
|
242
|
+
you'll need to run the v9 codemod before you run v10 and so on.
|
|
243
|
+
- The codemod will update your code to be compatible with the specified version, but it will **not**
|
|
244
|
+
remove outdated dependencies or upgrade dependencies to the latest version. You'll need to upgrade
|
|
245
|
+
dependencies on your own.
|
|
246
|
+
- We recommend upgrading dependencies before running the codemod.
|
|
247
|
+
- Always review your `package.json` files to make sure your dependency versions look correct.
|
|
248
|
+
- The codemod will not handle every breaking change in v13. You will likely need to make some manual
|
|
249
|
+
changes to be compatible. Use our Upgrade Guide as a checklist.
|
|
250
|
+
- Codemods are not bulletproof.
|
|
251
|
+
- Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
|
|
252
|
+
- As a safety precaution, we recommend committing the changes from the codemod as a single
|
|
253
|
+
isolated commit (separate from other changes) so you can roll back more easily if necessary.
|
|
254
|
+
|
|
255
|
+
We're here to help! Automatic changes to your codebase can feel scary. You can always reach out to
|
|
256
|
+
our team. We'd be very happy to walk you through the process to set you up for success.
|
|
257
|
+
|
|
258
|
+
## Running a Codemod
|
|
259
|
+
|
|
260
|
+
### Instructions
|
|
261
|
+
|
|
262
|
+
The easiest way to run our codemod is to use `npx` in your terminal.```sh
|
|
263
|
+
npx @workday/canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Be sure to provide specific directories that need to be updated via the `[path]` argument. This
|
|
267
|
+
decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
|
|
268
|
+
having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
|
|
269
|
+
if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
|
|
270
|
+
`[path]`.
|
|
271
|
+
|
|
272
|
+
Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
|
|
273
|
+
codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
|
|
274
|
+
finished.
|
|
275
|
+
|
|
276
|
+
```sh
|
|
277
|
+
yarn add @workday/canvas-kit-codemod --dev
|
|
278
|
+
yarn canvas-kit-codemod v${canvasKitMajorVersion} [path]
|
|
279
|
+
yarn remove @workday/canvas-kit-codemod
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
> **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
|
|
283
|
+
> manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
|
|
284
|
+
> after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
|
|
285
|
+
> your project conventions.
|
|
286
|
+
|
|
287
|
+
## Codemod Transformations for v15
|
|
288
|
+
|
|
289
|
+
The following automated transformations are available for upgrading to v15:
|
|
290
|
+
|
|
291
|
+
- **Promote Segmented Control**: promoteSegmentedControl
|
|
292
|
+
|
|
293
|
+
Run the codemod with: `npx @workday/canvas-kit-codemod v15 [path]`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workday/canvas-kit-mcp",
|
|
3
|
-
"version": "15.0.0-alpha.
|
|
3
|
+
"version": "15.0.0-alpha.0023-next.0",
|
|
4
4
|
"description": "MCP package for Canvas Kit",
|
|
5
5
|
"author": "Workday, Inc. (https://www.workday.com)",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -53,5 +53,5 @@
|
|
|
53
53
|
"tsx": "^4.7.0",
|
|
54
54
|
"typescript": "5.0"
|
|
55
55
|
},
|
|
56
|
-
"gitHead": "
|
|
56
|
+
"gitHead": "13b3abf5b4752be5738a78f3c37e31b6252077dc"
|
|
57
57
|
}
|