@workday/canvas-kit-docs

# Canvas Kit 10.0 Upgrade Guide This guide contains an overview of the changes in Canvas Kit v10. Please [reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have any questions. - [Codemod](#codemod) - [Features](#features) - [Styling](#styling) - [Removals](#removals) - [CSS Packages](#css-packages) - [useBanner](#useBanner) - [Deprecations](#deprecations) - [Input Icon Container](#input-icon-container) - [Select (Preview)](#select-preview) - [Space Numbers](#space-numbers) - [Table](#table) - [Token Updates](#token-updates) - [Space and Depth](#space-and-depth) - [Component Updates](#component-updates) - [Button](#button) - [Popups](#popups) - [Select (Main)](#select-main) - [Glossary](#glossary) - [Main](#main) - [Preview](#preview) - [Labs](#labs) ## Codemod Unlike past major releases, v10 does not have a codemod. The changes in v10 were either deemed infeasible to codemod or provided low ROI based on consumer usage. This is subject to change; if necessary, we can release codemods as minor updates. Codemods are here to stay and will continue to be a part of our release process. In the meantime, this Upgrade Guide should provide everything you need to update your code to be compatible with v10. ## Features ### Styling **PR:** [#2273](https://github.com/Workday/canvas-kit/pull/2273) We've introduced a new styling package `@workday/canvas-kit-styling` which is a wrapper around `@emotion/css`. If you're using Canvas Kit and not directly using this package, there is nothing extra to do on your end. The Canvas Kit packages are using the static compilation as part of the build process. If you want to use this package for your own styles, you don't need to do anything special to use in development; just reference our [documentation](https://workday.github.io/canvas-kit/?path=/docs/styling-getting-started--docs) on how to get started. For more information on why this package was introduced, please reference our [discussion](https://github.com/Workday/canvas-kit/discussions/2265) on the future of styling for Canvas Kit. ## Removals Removals from our codebase may no longer be consumed. We've either promoted or replaced the removed component or utility. ### CSS Packages **PR:** [#2368](https://github.com/Workday/canvas-kit/pull/2368) We've removed the `@workday/canvas-kit-css-*` packages from our source code. The packages have been in maintenance mode for a while with no updates, but still riding the wave of version updates. Starting in v10, our plan is to release our CSS kit as a static build straight from our React package and under the new `@workday/canvas-kit-css` package. This means we're not releasing an update to the CSS package in `10.0.0`, but will add our button CSS as a minor version. We're converting all our existing React packages to use this new styling strategy which will allow us to publish all CSS packages straight from the styles of our React packages, reducing the maitenance overhead required to maintain both our React kit and CSS kit. --- ### useBanner **PR:** [#2318](https://github.com/Workday/canvas-kit/pull/2318) We've removed the `useBanner` hook, the only function of which was to add `aria-labelledby` and `aria-describedby` references to the text inside of the Banner. This was not required for accessibility, and browsers can compute the name of the Banner from the text given inside. ## 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. ### Input Icon Container **PR:** [#2332](https://github.com/Workday/canvas-kit/pull/2332) We've deprecated `InputIconContainer` from [Main](#main) because it doesn't handle bidirectionality or icons at the start of an input. Please use [`InputGroup`](https://workday.github.io/canvas-kit/?path=/story/components-inputs-text-input--icons) instead. --- ### Select (Preview) **PR:** [#2309](https://github.com/Workday/canvas-kit/pull/2309) We've deprecated `Select` from [Preview](#preview). Please use [`Select` in Main](https://workday.github.io/canvas-kit/?path=/story/components-inputs-select--basic) instead. --- ### Space Numbers **PR:** [#2345](https://github.com/Workday/canvas-kit/pull/2345) We've deprecated `spaceNumbers`. Please use our `rem` based [`space`](https://workday.github.io/canvas-kit/?path=/docs/tokens--space) tokens. If you need to calculate a value, use [CSS calc()](https://developer.mozilla.org/en-US/docs/Web/CSS/calc) instead. ```tsx // With deprecated `spaceNumbers` { paddingLeft: spaceNumbers.xl + 2; // 42px } // With `rem` based `space` tokens { padding: `calc(${space.xl} + 2px)`; // 42px } ``` For more information on how to handle this migration, please reference our [discussion](https://github.com/Workday/canvas-kit/discussions/2343). --- ### Table **PR:** [#2344](https://github.com/Workday/canvas-kit/pull/2344) We've deprecated `Table` and `TableRow` and all of their exported members. Please use [`Table`](https://workday.github.io/canvas-kit/?path=/docs/preview-table--basic) in [Preview](#preview) instead. ## Token Updates ### Space and Depth **PR:** [#2229](https://github.com/Workday/canvas-kit/pull/2229) We've updated our `space` and `depth` token values from `px` to `rem`. This is based on the default browser font size which is `16px`. These updates simply mean that we have moved the values from `px` to `rem`. The values have been updated on a 1:1 basis. None of the base values have changed, only the unit. The table below shows what each token value is, what it corresponds to, and what the new `rem` value is in `px`: | px Value | rem Value | space Token | | -------- | --------- | ----------- | | 0 | 0 | zero | | 4px | 0.25rem | xxxs | | 8px | 0.5rem | xxs | | 12px | 0.75rem | xs | | 16px | 1rem | s | | 24px | 1.5rem | m | | 32px | 2rem | l | | 40px | 2.5rem | xl | | 64px | 4rem | xxl | | 80px | 5rem | xxxl | You can convert a `px` value to a `rem` value by dividing your `px` value by `16`(if your default browser font size hasn't been updated, the value will be `16`). For example: | Equation | rem Value | | ----------- | --------- | | `16px/16px` | `1rem` | | `32px/16px` | `2rem` | | `8px/16px` | `0.5rem` | #### Why Did We Make This Change? We wanted to move away from absolute units in tokens to relative units for better accessibility and adaptability to different viewport/screen sizes. If a user changes their default browser font size, these sizes should change along with it. `px` are a fixed unit and do not scale, whereas `rem` will allow these tokens to scale with a new default font size. ## Component Updates ### Button **PR:** [#2285](https://github.com/Workday/canvas-kit/pull/2285) We've refactored how we style buttons to use our [`createStyles`](https://workday.github.io/canvas-kit/?path=/docs/features-styling-api--create-styles) utility function. We don't anticipate this being a breaking change in most cases, but there may be slight changes to visual tests. #### Button Icon Fill Icons will no longer be incorrectly filled on toggle. #### Button Focus Ring Update We found that focus rings were not consistent across all buttons. We've updated the focus ring on the `inverse` variant of `PrimaryButton` to display a consistent focus ring across `PrimaryButton` and `SecondaryButton`. The changes to `PrimaryButton` will need to be taken note of due to small visual changes with the `inverse` variant. Also, `colors` will no longer support the `focusRing` option. ```tsx import {focusRing} from '@workday/canvas-kit-react/common'; // v9 <PrimaryButton colors={{ // other colors focus: { // other colors focusRing: focusRing(/* options */) } }} /> // v10 <PrimaryButton colors={{ // other colors focus: { // other colors } }} css={{ ':focus-visible': focusRing(/* options */) }} />; ``` --- ### Popups All Popup components including `Menu` and `Popup` have increased the top and bottom spacing between the target and popup to `4px`. --- ### Select (Main) **PR:** [#2309](https://github.com/Workday/canvas-kit/pull/2309) We've converted `Select` into a [compound component](/get-started/for-developers/documentation/compound-components/) which provides a flexible API and access to its internals via its subcomponents. ```tsx import {FormField} from '@workday/canvas-kit-react/form-field'; import {Select} from '@workday/canvas-kit-react/select'; // v9 <FormField label="Pizza Size"> <Select onChange={handleChange} value={value}> <SelectOption label="Small" value="small" /> <SelectOption label="Medium" value="medium" /> <SelectOption label="Large" value="large" /> </Select> </FormField>; ``` ```tsx import {FormField} from '@workday/canvas-kit-react/form-field'; import {Select} from '@workday/canvas-kit-react/select'; // v10 <Select items={['Small', 'Medium', 'Large']}> <FormField label="Pizza Size" inputId="pizza"> <Select.Input id="pizza" onChange={e => handleChange(e)} id="pizza" /> <Select.Popper> <Select.Card maxHeight="200px"> <Select.List> {item => { return <Select.Item>{item}</Select.Item>; }} </Select.List> </Select.Card> </Select.Popper> </FormField> </Select>; ``` Notice that `Select` is now outside the `FormField`. This is due to the update in `Select` and how the `FormField` in main applies attributes. Previously, `Select` was a styled native `<select>` input and `FormField` applied attributes automatically to that input. The new `Select` is solely a React context provider for its subcomponents. `FormField` needs `Select.Input` to be a direct child to apply attributes correctly. Also, unlike the [Select in Preview](https://workday.github.io/canvas-kit/?path=/story/preview-select-left-label--default), this component does not have a border around its menu. ## Glossary ### Main Our Main package of Canvas Kit tokens, components, and utilities at `@workday/canvas-kit-react` has undergone a full design and a11y review and is approved for use in product. Breaking changes to code in Main will only occur during major version updates and will always be communicated in advance and accompanied by migration strategies. --- ### Preview Our Preview package of Canvas Kit tokens, components, and utilities at `@workday/canvas-kit-preview-react` has undergone a full design and a11y review and is approved for use in product, but may not be up to the high code standards upheld in the [Main](#main) package. Preview is analagous to code in beta. Breaking changes are unlikely, but possible, and can be deployed to Preview at any time without triggering a major version update, though such changes will be communicated in advance and accompanied by migration strategies. Generally speaking, our goal is to eventually promote code from Preview to [Main](#main). Occasionally, a component with the same name will exist in both [Main](#main) and Preview (for example, see Segmented Control in [Preview](/components/buttons/segmented-control/) and [Main](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/components-buttons-segmented-control--basic)). In these cases, Preview serves as a staging ground for an improved version of the component with a different API. The component in [Main](#main) will eventually be replaced with the one in Preview. --- ### Labs Our Labs package of Canvas Kit tokens, components, and utilities at `@workday/canvas-kit-labs-react` has **not** undergone a full design and a11y review. Labs serves as an incubator space for new and 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).