# Canvas Kit 5.0 Upgrade Guide Below are the breaking changes made in Canvas Kit v5. Please [reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have any questions about the update. - [Codemod](#codemod) - [General Changes](#general-changes) - [Slash Imports](#slash-imports) - [Canvas Kit Preview](#canvas-kit-preview) - [Type Deprecations and Hierarchy Updates](#type-deprecations-and-hierarchy-updates) - [Canvas Kit CSS Maintenance Mode](#canvas-kit-css-maintenance-mode) - [Prop Interfaces](#prop-interfaces) - [Component Changes](#component-changes) - [Component Promotions](#component-promotions) - [Core](#core) - [Tokens](#tokens) - [Button](#button) - [Card](#card) - [Inputs](#inputs) - [Tabs](#tabs) - [Popper](#popper) - [Popups](#popups) - [Modal](#modal) - [Skeleton](#skeleton) ## Codemod We've introduced a [new codemod package](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) you can use to automatically update your code to work with a majority of the breaking changes in the upgrade from Canvas Kit v4 to v5. Simply run: ```sh > npx @workday/canvas-kit-codemod v5 [path] ``` > Note: This codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` extensions. You may need to make > some manual changes in other file types (`.json`, `.mdx`, `.md`, etc.). > Note: You may need to run your linter after executing the codemod, as it's resulting formatting > (spacing, quotes, etc.) may not match your project's styling. **Breaking changes accounted for by this codemod will be marked with a 🤖.** **Please verify all changes made by the codemod. As a safety precaution, we recommend committing the changes from the codemod as a single isolated commit (separate from other changes) so you can rollback more easily if necessary.** [Let us know](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you encounter any issues or use cases that we've missed. The `@workday/canvas-kit-codemod` package will help us maintain additional codemod transforms to make future upgrades easier. ## General Changes ### Slash Imports Rather than having a separate module for each component, we've moved to a slash imports system. All of our React components are now bundled in one of three modules: - `@workday/canvas-kit-react` - `@workday/canvas-kit-labs-react` - `@workday/canvas-kit-preview-react` > Note: See [Canvas Kit Preview](#canvas-kit-preview) for more information about the new > `@workday/canvas-kit-preview-react` module. Consequently, you'll need to update your import statements: ```tsx // v4 import {TextInput} from '@workday/canvas-kit-react-text-input'; // v5 import {TextInput} from '@workday/canvas-kit-react/text-input'; ``` 🤖 The codemod will update import statements to use the new slash imports syntax. Recall that the codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` extensions. Other file types will need to be updated manually. --- ### Canvas Kit Preview Due to the broad range of stability in [Canvas Kit Labs](https://github.com/Workday/canvas-kit/tree/master/modules/labs-react) (`@workday/canvas-kit-labs-react`), we've introduced a new module called [Canvas Kit Preview](https://github.com/Workday/canvas-kit/tree/master/modules/preview-react) (`@workday/canvas-kit-preview-react`) to provide consumers with more clarity and confidence when uptaking experimental and upcoming components. The components in Preview have had a full design and accessibility review and are approved for use in product. Their functionality and design are set, but their APIs and/or underlying architecture are still subject to change. Preview serves as a staging ground for components that are ready to use, but may not be up to the high code standards upheld in the Main `@workday/canvas-kit-react` module. Think of Labs as a space for alpha components and Preview as a space for beta components. We've promoted several components from Labs to Preview in v5. See [Component Promotions](#component-promotions) for more details. --- ### Type Deprecations and Hierarchy Updates Canvas Kit v4 supported two type hierarchies, Beta and Legacy in `@workday/canvas-kit-labs-react-core` and `@workday/canvas-kit-react-core` respectively. However, v5 replaces those with a new, responsive type hierarchy in `@workday/canvas-kit-react/tokens`. We are also deprecating and updating our type variants. The v5 codemod handles almost all of these changes for you. That said, you'll want to review the transformation and your UI to ensure everything was updated as you expect. #### Automatic Updates - 🤖 Type Hierarchy Updates All type hierarchy updates are handled by the codemod. The tables below will help you understand the changes and provide a reference as you review your UI. Most teams are using the Beta type tokens in `@workday/canvas-kit-labs-react-core`, but some are using the Legacy type in `@workday/canvas-kit-react-core`. | Legacy Type (px) | Responsive Type (rem) | | ----------------- | ---------------------------------------- | | `dataViz1` (56px) | `levels.title.large` (3.5rem \ 56px) | | `dataViz2` (34px) | `levels.heading.large` (2rem \ 32px) | | `h1` (28px) | `levels.heading.medium` (1.75rem \ 28px) | | `h2` (24px) | `levels.heading.small` (1.5rem \ 24px) | | `h3` (20px) | `levels.body.large` (1.25rem,) \ 20px | | `h4` (16px) | `levels.body.small` (1rem \ 16px) | | `h5` (16px) | `levels.body.small` (1rem \ 16px) | | `body` (14px) | `levels.subtext.large` (0.875rem \ 14px) | | `body2` (13px) | `levels.subtext.medium` (0.75rem \ 12px) | | `small` (12px) | `levels.subtext.medium` (0.75rem \ 12px) | - 🤖 Property Updates All `fontFamily`, `fontSize`, and `fontWeight` property updates are handled by the codemod. | CSS Property | Corresponding Token | Notes | | ------------ | ------------------------------ | --------------------------------------------------------------- | | `fontFamily` | `type.properties.fontFamilies` | `default` (Roboto) and `monospace` (Roboto Mono) are available | | `fontSize` | `type.properties.fontSizes` | please consult the type hierarchies above to map values | | `fontWeight` | `type.properties.fontWeights` | `regular` (400), `medium` (500), and `bold` (700) are available | - 🤖 Variant Updates All `variant` updates _except `link`_ are handled by the codemod. Please see the [variants](#variants) section below for more information. | Variant | Transformation | Notes | | ---------------------- | ------------------------------------------------------------------------------ | --------------------------------------- | | `type.variant.error` | `type.variants.error` | name change only | | `type.variant.hint` | `type.variants.hint` | name change only | | `type.variant.inverse` | `type.variants.inverse` | name change only | | `type.variant.button` | `{fontWeight: type.properties.fontWeights.bold}` | variant deprecated, use type properties | | `type.variant.caps` | `{textTransform: 'uppercase', fontWeight: type.properties.fontWeights.medium}` | variant deprecated, use type properties | | `type.variant.label` | `{fontWeight: type.properties.fontWeights.medium}` | variant deprecated, use type properties | | `type.variant.mono` | `{fontFamily: type.properties.fontFamilies.monospace}` | variant deprecated, use type properties | #### Manual Updates ##### TypeScript Type Updates - `CanvasType` still exists, but the types are quite different and will likely throw errors if you're relying on them. - `CanvasTypeVariant` is now `CanvasTypeVariants` and has changed signicantly - We added `CanvasTypeHierarchy` (for type levels) and `CanvasTypeProperties` (for type properties) ##### Code Deprecations There are only two type deprecations not covered by the codemod: - Type Wrapper components (`H1`-`H5`) have been removed - `link` variant has been removed ##### Type Wrapper Components Migration To migrate, please refer to the hierachy tables about and use the type hierarchy tokens directly. Detailed usage information is available in the [levels section](#levels). ##### Link Variant Migration To migrate, please use the `Hyperlink` component instead. Detailed usage information is available in the [variants section](#variants). #### Type Updates In-Depth Overview The new type tokens introduce a few major changes: - Introducing rem units - Creating a new `type` object structure - Adding new type properties (`fontFamilies`, `fontSizes`, and `fontWeights`) - Updating and replacing variants #### Introducing Rem Units The new type hierarchy uses `rem` units instead of `px`. This update follows the guidance [from the WCAG spec](https://www.w3.org/TR/WCAG21/#resize-text) and provides better support for users who rely on zooming. If you'd like to learn more about `rem` and relative units, you can review this [documentation](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#ems_and_rems). > **Note:** We are using `16px` as our base font-size for these values. This is a browser standard > and also fairly common across Workday. However, _if your body text is set to a value other than > `16px`_, you will need to adjust that value for text to render properly. #### New Type Object Structure The Beta and Legacy type object structures were fairly flat, provided many levels in the type hierarchy, and included quite a few variants. While none of these were bad attributes, our research suggested they created a large amount of confusion. Both designers and engineers were unclear on when to use many of the tokens provided. We restructured the object to help users make more sense of it. The tokens are divided into three main parts: - `levels` (the type hierarchy) - `properties` (`fontFamilies`, `fontSizes`, and `fontWeights`) - `variants` (modifiers for type styles) ##### Levels Type `levels` contain our new type hierarchy. When applying type styles, we recommend using these tokens first. Each size applies `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, and `color` styles for you, so you can create consistent type quickly and easily. Instead of the previous flat structure, the type hierarchy is now organized in four levels: - `title` (used for large page titles) - `heading` (used for headings and large text) - `body` (used for standard body text) - `subtext` (used for small subtext content or in tight spaces) And each level has three sizes: `large`, `medium`, and `small`. The previous hierarchy often mapped its levels 1:1 with semantic elements. This would often lead to awkward styling, such as this: ```tsx // v4 import {type} from '@workday/canvas-kit-labs-react-core'; // Why is an h2 styled with h3 styles? Is this intentional? Is this a mistake? I don't know. const PageSection = () => { return (

Section Heading

Section body text

); }; ``` But this new organization allows the hierarchy to be more flexible and create less confusion around usage. Below is an example: ```tsx // v5 import {type} from '@workday/canvas-kit-react/tokens'; const PageSection = () => { return (

Section Heading

Section body text

); }; ``` ##### Properties Most often you will want to reach for `levels`, but sometimes you only need one or two type values for styling. Previously, you had to use the hierarchy to apply these values, which is clunky and implicit. For example, using: `fontSize: type.h2.fontSize,` when all you really want is the token for `24px`. Type `properties` give you an atomic-level of control when you want to explicitly set a particular value. Here's an example using `fontFamilies`, `fontSizes`, and `fontWeights`. > _Note:_ `fontSizes` keys are in pixel values as a convenient reference, but the values are the > base-16 rem equivalent. E.g. `fontSizes[12]` returns `0.75rem`. ```tsx import {type} from '@workday/canvas-kit-react/tokens'; const boldTextStyles = { fontFamily: type.properties.fontFamilies.default, // 'Roboto' fontSize: type.properties.fontSizes[16], // 1rem (16px) fontWeight: type.properties.bold, // 700 }; const mediumMonoStyles = { fontFamily: type.properties.fontFamilies.monospace, // 'Roboto Mono' fontSize: type.properties.fontSizes[12], // 0.75rem (12px) fontWeight: type.properties.medium, // 500 }; ``` ##### Variants **Supported Variants** We're also reducing and simplifying our `variants`. In v5 we will only support: - `error` (used for making errors more visible) - `hint` (used for help text and secondary content) - `inverse` (used for any text on a dark or colored background) > **Note:** The `variant` key has been renamed to `variants` to be consistent with our other key > names. ```tsx //v4 import {type} from '@workday/canvas-kit-labs-react-core'; const errorStyles = type.variant.error; const hintStyles = type.variant.hint; const inverseStyles = type.variant.inverse; // v5 import {type} from '@workday/canvas-kit-react/tokens'; const errorStyles = type.variants.error; const hintStyles = type.variants.hint; const inverseStyles = type.variants.inverse; ``` **Deprecated Variants** We've deprecated a handful of variants: - `button` - `caps` - `label` - `link` - `mono` With the exception of `link`, which is discussed further below, all of these variants can be supported with `properties` and other styles. Here are examples of how to translate each deprecated variant: ```tsx //v4 import {type} from '@workday/canvas-kit-labs-react-core'; // button variant styles const buttonStyles = type.variant.button; // caps variant styles const capsStyles = type.variant.caps; // label variant styles const labelStyles = type.variant.label; // mono variant styles const monoStyles = type.variant.mono; // v5 import {type} from '@workday/canvas-kit-labs-react/tokens'; // button variant styles const buttonStyles = {fontWeight: type.properties.fontWeights.bold}; // caps variant styles const capsStyles = { fontWeight: type.properties.fontWeights.medium, textTransform: 'uppercase', }; // label variant styles const labelStyles = {fontWeight: type.properties.fontWeights.medium}; // mono variant styles const monoStyles = {fontFamily: type.properties.fontFamilies.monospace}; ``` **Link Variant** The `link` variant is also being deprecated in v5. You'll need to use the `Hyperlink` component instead. This is the only manual update needed for the type updates. Below are some examples: ```tsx // v4 import {type} from '@workday/canvas-kit-labs-react-core'; const Link = styled('a')(type.variant.link); return View docs; // v5 import {Hyperlink} from '@workday/canvas-kit-labs-react/button'; return View docs; ``` > **Note:** If you're mixing styles from type `levels`, you'll need to pull out the `color` style > when applying them to `Hyperlink`. Below is an example. ```tsx // v5 import {type} from '@workday/canvas-kit-labs-react/tokens'; import {Hyperlink} from '@workday/canvas-kit-labs-react/button'; // Remove `color` from type styles to prevent the color from overriding the link color const {color, ...headingLargeStyles} = type.levels.heading.large; const HeadingLink = () => ( View docs ); ``` --- ### Canvas Kit CSS Maintenance Mode Due to the infrequent use of our CSS modules, we've placed them in maintenance mode in v5. Although we'll continue to support `@workday/canvas-kit-css` with bug fixes and significant visual updates, it most likely won't be receiving new components or additional features. This will allow us to provide more focused support and to dedicate our efforts to making bigger and better improvements to our most used components: Canvas Kit React. If you have questions or concerns, please [let us know](https://github.com/Workday/canvas-kit/discussions/new). ### Prop Interfaces Many components were updated to be polymorphic using the `createComponent` utility function. Most components in Canvas Kit extend from an HTML interface and spread extra props onto the HTML element. Since these components are now polymorphic, the exported props no longer extend from an HTML interface since the HTML interface is now determined by an optional `as` prop. It is common to wrap Canvas Kit components with your own component and extend from the Canvas Kit component's prop interface. To support this use-case in addition to polymorphic prop interfaces, `ExtractProp` was introduced. `ExtractProp` understands these polymorphic components and will return the base props in addition to the HTML interface. There is an optional second argument that can override the default HTML interface if your wrapper component uses the `as`. ```tsx // v4 import {TextInput, TextInputProps} from '@workday/canvas-kit-react-text-input'; const FancyTextInput: React.FC = props => ; // v5 import {TextInput} from '@workday/canvas-kit-react/text-input'; import {ExtractProps} from '@workday/canvas-kit-react/common'; const FancyTextInput: React.FC> = props => {}; // v5 via createComponent import {TextInput} from '@workday/canvas-kit-react/text-input'; import {createComponent} from '@workday/canvas-kit-react/common'; const FancyTextInput = createComponent(TextInput)({ displayName: 'FancyTextInput', Component((props) => ) }) ``` Components that made this change: - Button - IconButton - Card - Hyperlink - Select - TextArea - TextInput - Checkbox - Radio - ColorInput - ColorPreview - Modal - Popup - Skeleton - Tabs - Toast ## Component Changes ### Component Promotions #### Promotions from Labs to Preview The following components were promoted from Labs to the new Preview module: - Breadcrumbs - Color Picker - Menu - Select - Side Panel You'll need to update your imports for promoted components (this is _not_ handled by the codemod): ```tsx // v4 import {Breadcrumbs} from '@workday/canvas-kit-labs-react-breadcrumbs'; // v5 import {Breadcrumbs} from '@workday/canvas-kit-preview-react/breadcrumbs'; ``` #### Promotions from Labs to Main Generally, a component will begin in Labs before it's promoted to Preview and eventually to Main (although there is no guarantee a component will advance out of Labs). Given that Preview was just introduced in v5, however, we believe that a few components have incubated long enough in Labs and are ready for Main. The following components have been promoted straight from Labs to Main: - Pagination - Tabs These imports will need to be updated manually as well (this is _not_ handled by the codemod): ```tsx // v4 import {Pagination} from '@workday/canvas-kit-labs-react-pagination'; // v5 import {Pagination} from '@workday/canvas-kit-react/pagination'; ``` --- ### Core #### Remove Labs Core The Labs `core` package has been removed. The few utilities in that package were either promoted, deprecated, or found a better home in another package. These changes are listed below, most of which are handled by the v5 codemod. ##### Automatic Updates - 🤖 Move `StaticStates` component to Main `common` We use `StaticStates` internally for our visual regression tests. It didn't really make sense to live in `core`, and it's stable enough to move to Main, so it now lives in `common`. ```tsx // v4 import {StaticStates} from '@workday/canvas-kit-labs-react-core'; // v5 import {StaticStates} from '@workday/canvas-kit-react/common'; ``` - 🤖 Move `type` tokens to Main `tokens` (formerly `core`) This change is described in more detail in the [Type Section](#type), but suffice to say all `type` imports will be automatically migrated to the Main `token` package by the codemod. ```tsx // v4 import {type} from '@workday/canvas-kit-labs-react-core'; // v5 import {type} from '@workday/canvas-kit-react/tokens'; ``` ##### Manual Updates - Deprecate `space` in favor of `Box` The `space` function was a handy little utility that you could apply to `styled()` components to add space style props. However, with the addition of `Box` it is no longer needed. `Box` provides `space` style props and much more. While this is a manual migration, the process is fairly straight-forward. > **Note:** The `space` props use shorthand prop names for what `Box` provides. For example, `pt` > maps to `paddingTop`, `mr` maps to `marginRight`, and so on. You can see this in the example > below. ```tsx // v4 import {spaceNumbers} from '@workday/canvas-kit-react-core'; import {space} from '@workday/canvas-kit-labs-react-core'; // A styled div with space props const Box = styled('div')(space); const Card = () => Hello!; // v5 import {Box} from '@workday/canvas-kit-labs-react/common'; const Card = () => Hello!; ``` #### Rename Core to Tokens The distinction between our core and common packages is often unclear and creates confusion around what should be imported from where. To help alleviate this and better align with our design taxonomy, we've renamed our Main `core` module to `tokens`. These changes are listed below, all of which are handled by the v5 codemod. ##### Automatic Updates - 🤖 Rename Main `core` import statements to `tokens` ```tsx // v4 import {colors} from '@workday/canvas-kit-react-core'; // v5 import {colors} from '@workday/canvas-kit-react/tokens'; ``` #### Input Provider The `InputProvider` wrapper component (used to provide CSS-referencable data attributes for the user's current input method) has been moved from `@workday/canvas-kit-react-core` to `@workday/canvas-kit-react/common`. After renaming our `core` package to `tokens`, it no longer made sense in this location. ```tsx // v4 import {InputProvider} from '@workday/canvas-kit-react-core'; // v5 import {InputProvider} from '@workday/canvas-kit-react/common'; ``` 🤖 The codemod will update your `InputProvider` imports. --- ### Tokens #### Space To better align with our design taxonomy, we've renamed our space tokens in our `tokens` package (formerly in `core`). Instead of relying on `@workday/canvas-space-web` to supply our space values, we're now keeping those values in canvas-kit. We've also taken the opportunity to improve the space types (which were too generic) and their JSDoc hints. The following table describes each update: | Before | After | Change Description | | --------------------- | ------------------------- | -------------------------------- | | `spacing` | `space` | name change only | | `spacingNumbers` | `spaceNumbers` | name change only | | `CanvasSpacing` | `CanvasSpace` | name change and improved types\* | | `CanvasSpacingValue` | `CanvasSpaceValues` | name change only | | `CanvasSpacingNumber` | `CanvasSpaceNumbers` | name change and improved types\* | | `n/a` | `CanvasSpaceNumberValues` | new type! | \* Before, the types were too generic and not very useful. They now better reflect the values they represent. The codemod will handle _almost all_ of these changes for you.That said, you'll want to review your UI to ensure everything was updated as you expect. [Manual Updates](#manual-updates) below. ##### Automatic Updates - 🤖 Rename `spacing` and `spacingNumbers` imports. ```tsx // v4 import {spacing, spacingNumbers} from '@workday/canvas-kit-react-core'; // v5 import {space, spaceNumbers} from '@workday/canvas-kit-react/tokens'; ``` - 🤖 Rename `CanvasSpacing`, `CanvasSpacingValue`, and `CanvasSpacingNumber` imports. ```tsx // v4 import { CanvasSpacing, CanvasSpacingValue, CanvasSpacingNumber, } from '@workday/canvas-kit-react-core'; // v5 import { CanvasSpace, CanvasSpaceValues, CanvasSpaceNumbers, } from '@workday/canvas-kit-react/tokens'; ``` - 🤖 Update token expressions. ```tsx // v4 const iconPadding = spacing.s; // v5 const iconPadding = space.s; ``` - 🤖 Update type expressions. ```tsx // v4 const getSpace = (value: CanvasSpacingValue) => spacing[value]; // v5 const getSpace = (value: CanvasSpaceValue) => space[value]; ``` - 🤖 Update token properties. ```tsx // v4 const iconPadding = canvas.spacing.s; // v5 const iconPadding = canvas.space.s; ``` ##### Manual Updates As previously mentioned, the codemod should handle the vast majority of these updates. However, there are potentially a few changes that will need to be made manually. There may be more beyond what's listed below, but these were the most common issues found in our investigation. - Usage outside of `.js`, `.jsx`, `.ts`, and `.tsx` files - e.g. referencing `spacing` in documentation (`.md` files) - Usage in code comments or JSDoc comments - e.g. `// spacing.s = 16px` - Re-declararation `space` or `spaceNumbers` in the same files - e.g. importing or declaring a new `space` or `spaceNumbers` variable will prevent the codemod from updating the file - Aliasing existing variables as `spacing` or `spaceNumbers` - e.g. `import {spacingNumbers as spacing}` will prevent the codemod from updating the file #### Border Radius We've updated the border radius `zero` token value from `0` to `"0px"` for consistency given that all other border radius tokens use string pixel values. We highly doubt this change will cause any issues, but because the value's type is different, this is technically a breaking change. ```tsx // v4 import {borderRadius} from '@workday/canvas-kit-react-core'; console.log(borderRadius.zero); // returns `0` // v5 import {borderRadius} from '@workday/canvas-kit-react/tokens'; console.log(borderRadius.zero); // returns "0px" ``` --- ### Button #### Recategorization There has been common confusion around the large number of buttons Canvas supports and when each should be used. To improve the usability of our design system, we've been working to recategorize and simplify our button offering. To align with the recent changes in our Figma libraries, we've reorganized our buttons, renaming a few and removing others. The majority of button use cases have been simplified into three different components: `PrimaryButton`, `SecondaryButton`, and `TertiaryButton`, each level representing its emphasis and hierarchy in a UI. We hope this makes your usage of our buttons more intentional and clear. We've provided a codemod to make these changes automatically. **Renamed:** - 🤖 `Button` has been split into `PrimaryButton` and `SecondaryButton` (depending on the `variant` prop). - 🤖 `OutlineButton` (`secondary`) is now `SecondaryButton`. For accessibility reasons, the "outline" styling is the new styling for our secondary buttons. - 🤖 `OutlineButton` (`inverse`) is now `SecondaryButton` with an `inverse` variant. - 🤖 `TextButton` is now `TertiaryButton`. **Removed:** - 🤖 `HighlightButton`. Use `SecondaryButton` instead. - 🤖 `OutlineButton` with `primary` variant. Use `PrimaryButton` or `SecondaryButton` instead. The codemod will replace with `SecondaryButton`. - 🤖 `DropdownButton`. This can be achieved simply using `PrimaryButton` or `SecondaryButton` with an `icon` prop and `iconPosition="right"`. To see examples of code in v4 versus v5, see our [codemod tests](https://github.com/Workday/canvas-kit/tree/master/modules/codemod/lib/v5/spec/recategorizeButtons.spec.ts). #### Exports We've changed some of the Button module's export behavior: - 🤖 The `beta_Button` export was removed. The codemod will rename the import to `Button` instead, preserving local renaming if it exists. ```tsx // v4 import {beta_Button as Button} from '@workday/canvas-kit-react-button'; // v5 import {SecondaryButton} from '@workday/canvas-kit-react/button'; ``` - 🤖 The default export was removed. The codemod will change default imports to named imports. ```tsx // v4 import Button from '@workday/canvas-kit-react-button'; // v5 import {SecondaryButton} from '@workday/canvas-kit-react/button'; ``` #### Enums Enums have been removed from all buttons in favor of string literals. 🤖 The codemod will rewrite any usages of an enum to the string literal. If you used an enum as a type, the codemod will expand to a union of string literals. You could change the union manually instead to be something like `SecondaryButtonProps['variant']` if you prefer not to duplicate the union of string literals. ```tsx // v4 ); }; ``` #### v5 ```tsx import React from 'react'; import {DeleteButton} from '@workday/canvas-kit-react/button'; import { Popup, usePopupModel, useCloseOnEscape, useCloseOnOutsideClick, useInitialFocus, useReturnFocus, } from '@workday/canvas-kit-react/popup'; export const MyPopup = () => { const model = usePopupModel(); useCloseOnOutsideClick(model); useCloseOnEscape(model); useInitialFocus(model); // new useReturnFocus(model); // new const onDeleteClick = () => { console.log('Delete'); }; return ( Delete Item Delete Item

Are you sure you'd like to delete the item titled 'My Item'?

Delete Cancel ); }; ``` Most notably, `Popup` is now a container component that takes a `PopupModel` and has several subcomponents like `Popup.Target` and `Popup.CloseButton`. These components are hooked up to the `PopupModel` via React context and have access to state and events. `Popup.Card` is what the v4 `Popup` once was. All behavior hooks, like `useCloseOnEscape` now take a `model` instead of variable parameters. This allowed us to fix some subtle bugs. Using the `PopupModel` means all hooks have access to all Popup state and events without passing in many parameters. #### usePopup and usePopupModel As shown in the example above, `usePopupModel` should now be used instead of `usePopup`. All subcomponents have an associated behavior hook. For example, `Popup.Target` uses a hook called `usePopupTarget`. If you need to use your own components for any reason, these hooks are available. `Popup.Target` and `Popup.CloseButton` do not include any styling. They both render `SecondaryButton` by default. You can change this via the `as` prop. For example, the following will render an unstyled button: ```tsx Show ``` Pass a `css` prop or a styled button instead to have a custom styled button. You could even pass `IconButton` if you need an icon button to show a Popup instead! If you were using `usePopup` before, here's a list of equivalent APIs: | Before | After | | ----------------------------------------------------------------------- | ------------------------------------- | | `const { popperProps, targetProps, closePopup, stackRef } = usePopup()` | `const model = usePopupModel()` | | `popperProps.open` | `model.state.visibility !== 'hidden'` | | `closePopup()` | `model.events.hide()` | | `stackRef` or `popperProps.ref` | `model.state.stackRef` | | `popperProps.anchorElement` | `model.state.targetRef.current` | | `targetProps.onClick` | `usePopupTarget(model).onClick` | #### New Focus Management A common theme we noticed in uses of Popup in the wild was focus management. Developers were manually passing a `ref` to the target button element and manually returning focus to it when closing the Popup. This use case should now be handled by the new `useReturnFocus` hook. By default, `useReturnFocus` will return focus to the `targetRef` in the model, which is set by `Popup.Target`. This can be overridden by passing `returnFocusRef` to the model on creation. `returnFocusRef` should make your migration easier if `Popup.Target` cannot be used for whatever reason. ```tsx // before const {closePopup} = usePopup(); // passed to some event handler const closeAndReturnFocus = () => { closePopup(); buttonRef.current.focus(); }; // after const model = usePopupModel({ returnFocusRef: buttonRef, // only use if you cannot use `Popup.Target` }); useReturnFocus(model); ``` Another common use case involved focusing something within the Popup when the Popup was shown. The `useInitialFocus` hook was created for this purpose. `useInitialFocus` will set focus to the first focusable element when the Popup becomes visible. This behavior can be overridden by passing `initialFocusRef` to the model. ```tsx // before const {stackRef, popperProps} = usePopup(); useLayoutEffect(() => { if (!open) { return; } stackRef.current.querySelector('input,...').focus(); }, [popperProps.open]); // after const model = usePopupModel({ initialFocusRef: someRef, // only use if you want to explicitly focus on something. Could be useful for an input. }); useInitialFocus(model); ``` #### Managing Positioning If you'd prefer to manage positioning yourself, you can use `Popup.Card` on its own. Without the model and behaviors, the following is equivalent: ```tsx // v4 Popup Content // v5 Popup Heading Popup Content ``` `Popup.Card` uses `Card`, which is now using `Box`. Consequently, the following props have changed: | Before | After | | ------------------------------ | ------------------------------------------ | | `padding={Popup.Padding.zero}` | `padding="zero"` or `padding={space.zero}` | | `depth={depth[0]}` | `depth={0}` | | `popupRef={ref}` | `ref={ref}` | #### Transitioning We noticed Popups were used in two different ways: always rendering and conditional rendering. ```tsx // Always rendering const MyPopup = () => { const targetRef = React.useRef(null) const {stackRef, popperProps, targetProps, closePopup} = usePopup() const handleClose = () => { closePopup() targetRef.current.focus() // focus back on target } useCloseOnEscape(stackRef, handleClose) return ( <> {/* content */} ) } // Conditional rendering const MyOpenPopup = ({onClose, targetRef}) => { const {popperProps, closePopup} = usePopup() const handleClose = () => { onClose() closePopup() targetRef.current.focus() // focus back on target } useCloseOnEscape(stackRef, handleClose) return ( {/* content */} ); }; ``` #### v5 ```tsx import React from 'react'; import {Modal} from '@workday/canvas-kit-react/modal'; import {DeleteButton} from '@workday/canvas-kit-react/button'; import {HStack} from '@workday/canvas-kit-labs-react'; const MyModal = () => { const handleDelete = () => { console.log('Deleted item'); }; return ( Delete Item Delete Item

Are you sure you want to delete the item?

Delete Cancel ); }; ``` Most notably, `Modal` is now a container component that takes a `ModalModel` and has several subcomponents. `Modal` looks much like the structure of [Popups](#popups), except `Modal` has a `Modal.Overlay` subcomponent instead of a `Popup.Popper` component. The `Modal.Overlay` is the component in charge of adding an element to the `PopupStack`. We noticed some application code that do custom focus management. There were some subtle issues like #694 (VoiceOver on iOS not returning focus). v5 introduced focus management behaviors like `useInitialFocus` and `useReturnFocus` that should work more consistently. Most of the special focus management code could be removed when using v5 the `Modal`. #### useModal and useModalModel As shown in the example above, `useModal` has been removed. The `Modal` container component will provide a pre-configured `PopupModel` via the `useModalModel` function. In v4, `useModal` returned a `closeModal` callback function that you'd call to close the `Modal`. In v5, `Modal.CloseButton` takes care of this for you. If you need to close the `Modal` outside a button, you can hoist the model and use the model's `hide` event: ```tsx // v4 const {closeModal} = useModal(); // somewhere in your code closeModal(); // v5 const model = useModalModel(); // somewhere in your code model.events.hide(); ``` #### handleClose In v4, `Modal` took a `handleClose` that doubled as a switch to show a close icon and a switch for modal closing for the Escape key and clicking outside the `Modal`. In v5, the `Modal.CloseIcon` subcomponent controls the rendering of the icon. If you need to disable the Escape key or clicking outside the `Modal`, you'll have to create your own `PopupModel` instead and pass that to the `Modal` container component. ```tsx const model = usePopupModel(); // not `useModalModel` // disable useCloseOnEscape and useCloseOnOverlayClick useInitialFocus(model); useReturnFocus(model); useFocusTrap(model); useAssistiveHideSiblings(model); useDisableBodyScroll(model); return {/* ... */}; ``` --- ### Skeleton Skeleton was already implemented as a compound component in v4, but we've made changes to its imports and to its animation in v5. The imports for its subcomponents in v4 (`SkeletonHeader`, `SkeletonText`, and `SkeletonShape`) have been converted to keys on `Skeleton` in v5 (`Skeleton.Header`, `Skeleton.Text`, and `Skeleton.Shape`). You only need to import the `Skeleton` component in v5, and you may still compose your own Skeleton using whatever parts you need. ```tsx // v4 import { Skeleton, SkeletonHeader, SkeletonShape, SkeletonText, } from '@workday/canvas-kit-react/skeleton'; const MySkeleton = () => ( ); // v5 import {Skeleton} from '@workday/canvas-kit-react/skeleton'; const MySkeleton = () => ( ); ``` Additionally, the Skeleton animation has been updated from a diagonal sheen, or shimmer, to fading the opacity of the entire shape(s) in and out.