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