@workday/canvas-kit-docs 9.0.0-alpha.382-next.2 → 9.0.0-alpha.384-next.3

package/dist/mdx/9.0-UPGRADE-GUIDE.mdx

@@ -5,20 +5,26 @@ This guide contains an overview of the changes in Canvas Kit v9. Please
 any questions.
 
 - [Codemod](#codemod)
-- [Component Deprecations](#component-deprecations)
+- [Removals](#Removals)
   - [Drawer](#drawer)
   - [Layout and Column](#layout-and-column)
-  - [Stack](#stack-hstack-vstack)
-- [Component Updates](#component-updates)
-  - [Buttons](#buttons) - [Toast](#toast)
-- [Utility Updates](#utility-updates)
+  - [Stack, HStack, and VStack](#stack-hstack-and-vstack)
   - [focusRing](#focusring)
-  - [useTheme and getTheme](#useTheme-and-getTheme)
-  - [useCanvasTheme and getCanvasTheme](#useCanvasTheme-and-getCanvasTheme)
-  - [useThemedRing](#useThemedRing)
-  - [useThemeRTL](#useThemeRTL)
+  - [useCanvasTheme and getCanvasTheme](#usecanvastheme-and-getcanvastheme)
+- [Deprecations](#deprecations)
+	- [useThemeRTL](#usethemertl)
 - [Token Updates](#token-updates)
   - [Depth](#depth)
+- [Component Updates](#component-updates)
+  - [Button](#button)
+  - [Toast](#toast)
+- [Utility Updates](#utility-updates)
+  - [useTheme and getTheme](#usetheme-and-gettheme)
+  - [useThemedRing](#usethemedring)
+- [Glossary](#glossary)
+  - [Main](#main)
+  - [Preview](#preview)
+  - [Labs](#labs)
 
 ## Codemod
 
@@ -51,157 +57,262 @@ handled by the codemod are marked with 🤖 in the Upgrade Guide.**
 the changes from the codemod as a single isolated commit (separate from other changes) so you can
 roll back more easily if necessary.
 
-## Component Deprecations
+## Removals
+Removals are deletions from our codebase and you can no longer consume this component.
+We've either promoted or replaced a component or utility.
+
 
-### Deprecation Types
 
-#### Soft Deprecation
 
-A soft-deprecated component is still available with its full functionality, but it will have been
-renamed with a prefix to indicate its soft-deprecated status. It will also include a console warning
-announcing its deprecation. This warning will only be triggered on the component's initial render.
+### Drawer
 
-Soft-deprecated types and utilities will also have been renamed but generally will not trigger a
-console warning.
+**PR:** [#1970](https://github.com/Workday/canvas-kit/pull/1970)
 
-#### Hard Deprecation
+We've removed the `Drawer` component (for reference, see the
+[`Drawer`](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/labs-drawer--basic) from v8). Please
+use the [`SidePanel`](/components/containers/side-panel/) in [Preview](#preview) instead.
 
-A hard-deprecated component or package is no longer available. You will need to follow the method
-prescribed in our Upgrade Guide to update your application. Please
-[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) to our team
-directly if you need additional help.
+> **Note:** The `SidePanel` in Main will eventually be replaced with the `SidePanel` in Preview. We
+> recommend you use the `SidePanel` in Preview until then.
 
 ---
 
-### Drawer
+### Layout and Column
 
-<!---
-TODO: Please review this section with documenting SidePanel deprication
--->
+**PR:** [#2018](https://github.com/Workday/canvas-kit/pull/2018)
 
-We've [hard-deprecated](#hard-deprecation) `Drawer` and this component has been fully removed from
-Canvas Kit. Consider using the
-[Side Panel](https://workday.github.io/canvas-kit/?path=/story/preview-side-panel--basic). Be Aware
-that `SidePanel` from the Main package is planned to be replaced by the one from Preview. We suggest
-you use the Preview version of `SidePanel` until the one in Main is replaced with it.
+We've removed the `Layout` and `Column` components (for reference, see
+[`Column and Layout`](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/components-containers-column-and-layout--12-column-layout)
+from v8). Please use [`Grid`](/components/layout/grid/) instead. While `Grid` is not a 1:1
+replacement for `Layout` and `Column`, it can be used to generate the same types of layouts and
+offers a more robust and flexible layout solution.
+
+Please refer to our [Layout examples](/examples/layout/) for examples of how to implement common
+layouts using `Grid`.
 
 ---
 
-### Layout and Column
+### Stack, HStack and VStack
+
+**PR:** [#2012](https://github.com/Workday/canvas-kit/pull/2012)
+
+We've removed the `Stack`, `HStack`, and `VStack` components (for reference, see
+[`Stack`](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/components-layout-stack--basic-stack)
+from v8). Please use [`Flex`](/components/layout/flex/) instead. `Flex` supports the same consistent
+spacing between its elements via the `gap` prop (analogous to the `spacing` prop from `Stack`).
+
+```tsx
+// v8
+<Stack spacing="s">
+  ...
+</Stack>
+
+// v9
+<Flex gap="s">
+  ...
+</Flex>
+```
+
+The orientation of `VStack` elements can be replicated with `Flex` using `flexDirection`.
+
+```tsx
+// v8
+<VStack>
+  ...
+</VStack>
+
+// v9
+<Flex flexDirection="column">
+  ...
+</Flex>
+```
+
+The `StackProps`, `HStackProps`, `VStackProps`, and `StackStyleProps` types have been removed as
+well. All references to these types in your custom components will need to be replaced with
+`FlexProps`.
+
+🤖 The codemod will handle all of the changes above for you automatically.
+
+> **Note:** If you were consuming `StackProps` previously for a custom component, be sure to change
+> all references to the old `spacing` prop from `StackProps` to the `gap` prop from `FlexProps`.
+
+---
+
+### focusRing
+
+**PR:** [#2034](https://github.com/Workday/canvas-kit/pull/2034)
+
+We've removed memoization from `focusRing`. The `memoize` argument passed to `focusRing` is no
+longer valid, and we've removed `memoizedFocusRing`. We were unable to find any examples of
+`memoize` or `memoizedFocusRing` in use by our consumers.
+
+---
+
+### useCanvasTheme and getCanvasTheme
+
+**PR:** [#2120](https://github.com/Workday/canvas-kit/pull/2120)
+
+We've removed `useCanvasTheme` and `getCanvasTheme`. Please use `useTheme` and `getTheme` instead.
 
-`Layout` and `Column` components have been [hard-deprecated](#hard-deprecation) and are no longer
-available in Canvas Kit. Please consider using
-[`Grid`](https://workday.github.io/canvas-kit/?path=/docs/components-containers-grid--basic)
-instead. While the `Grid` component is not a 1:1 replacement for `Layout`, it can be used in the
-same way and offers several benefits over the deprecated components as a more robust and flexible
-layout solution.
+## Deprecations
 
-Please refer to
-[the Examples section](https://workday.github.io/canvas-kit/?path=/docs/examples-layouts--custom-column-positioning)
-for ideas on how to replace the deprecated `Layout` component with the `Grid` component. This will
-provide you with a deeper understanding of how to set custom column width or positioning using the
-`Grid` component.
+We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) from JSDoc to code that we plan to deprecate in the near future.
+Al though you can still consume this code, we want consumers to move to a utility or component that is more stable.
+
+### useThemeRTL
+
+**PR:** [#2119](https://github.com/Workday/canvas-kit/pull/2119)
+
+We've deprecated `useThemeRTL` from [Labs](#labs). Although you may still use this utility, we recommend
+using
+[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
+instead.
 
 ---
 
-### Stack, HStack and vstack
+## Token Updates
+
+### Depth
 
-We've hard deprecated the `Stack`, `HStack` and `VStack` components along with the props associated
-to those components (`StackProps`, `HStackProps`, `VStackProps`, `StackStyleProps`). We recommend
-using the `Flex` component and to replace the `spacing` prop with the `gap` prop. You can also run
-`npx @workday/canvas-kit-codemod v9 [path]`.
+**PR:** [#2091](https://github.com/Workday/canvas-kit/pull/2091)
 
-> **Note**: If you are consuming `StackProps` for a custom component, please make sure to change the
-> `spacing` prop to the `gap` prop
+In v7, we released an update to our depth tokens that was too bold and harsh for web applications.
+We've modified the depth token styles to be more subtle and improve visual design. This change
+affects all components which use depth tokens including `Card`, `Toast`, `Dialog`, `Popup`, `Modal`,
+and `Menu`. We have not changed which depth values each component references (i.e., `Card` remains
+at `depth[1]`).
 
 ## Component Updates
 
-### Buttons
+### Button
+
+**PR:** [#1978](https://github.com/Workday/canvas-kit/pull/1978)
+
+We've changed the default `type` attribute for all buttons to `type="button"`. Previously, the
+`type` attribute was not being set which resulted in the buttons
+[defaulting to `type="submit"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes).
 
-We've changed the default `type` attribute of all our `buttons` to be `type="button"` instead of the
-default `type="submit"`. This is a breaking change if you expected a button to submit by default.
+This affects all buttons which extend `BaseButton`:
 
-We found an issue where the default action for `form` controls like `input` and `textarea` is to
-click the first `submit` `button` which in some cases is not a `submit` button.
+- `PrimaryButton`
+- `SecondaryButton`
+- `TertiaryButton`
+- `DeleteButton`
+- `ToolbarDropdownButton` and `ToolbarIconButton`
+- `Pill` and `Pill.IconButton`
+- `SegmentedControl.Button` (Main)
+- `SegmentedControl.Item` (Preview)
+- `Pagination.PageButton`
 
-An example of this causing issues was our `Modal.CloseIcon` and `Modal.CloseButton`. When the
-`Modal` is wrapped in a `form` element, the close icon would submit the `form`.
+Any buttons which extend any of the above are affected as well.
 
-This change affects all of our `buttons` including:
-`PrimaryButton, SecondaryButton, TertiaryButton, ToolbarButton`.
+This resolves an [issue](https://github.com/Workday/canvas-kit/issues/1938) where clicking certain
+buttons within a `form` element would unexpectedly submit the form. Additionally, the default action
+of many form controls such as `input` and `textarea` is to click the first submit button; this led
+to issues if the first submit button in the form was not intended to be a submit button (a common
+mistake when buttons default to `type="submit"`).
 
-If you still wish for a specific `button` within a `form` to submit, just add the attribute
-`type="submit"`.
+This is a breaking change if you expected a button to submit by default, though we do not anticipate
+this to be the case for most developers. If you _do_ intend for a button to act as a submit button
+within a form, add `type="submit"` to the button.
+
+---
 
 ### Toast
 
-We've promoted `Toast` from Labs (`@workday/canvas-kit-labs-react`) to the Main
-(`@workday/canvas-kit-react`) package.
+**PR:** [#2044](https://github.com/Workday/canvas-kit/pull/2044)
 
-- This component is a
-  [compound component](/getting-started/for-developers/resources/compound-components/).
-- It has a `mode` prop that allows for proper accessibility attributes to be defined.
-- Its sub components allow for more flexibility and access to lower level elements.
+We've promoted `Toast` from [Labs](#labs) to [Main](#main). It replaces the `Toast` that was previously in [Main](#main) (for
+reference, see
+[`Toast`](https://d2krrudi3mmzzw.cloudfront.net/v8/?path=/docs/components-popups-toast--error) in
+[Main](#main) from v8).
+
+`Toast` is a [compound component](/getting-started/for-developers/resources/compound-components/)
+which provides a flexible API and access to its internals via its subcomponents. It supports a new
+`mode` prop which applies the proper accessibility features to the component based on the desired
+mode: `status`, `alert`, or `dialog`.
 
 ```tsx
 // v8
-<Toast actionText="View more details" onClose={handleClose}>Your workbook was successfully processed.</Toast>
+<Toast actionText="View more details" onActionClick={handleActionClick} onClose={handleClose}>
+  Your workbook was successfully processed.
+</Toast>
 
 // v9
 <Toast mode="dialog">
   <Toast.Icon icon={checkIcon} color={colors.greenApple400} />
   <Toast.Body>
     <Toast.Message>Your workbook was successfully processed.</Toast.Message>
-    <Toast.Link href="#hreflink">Custom Link</Toast.Link>
+    <Toast.Link onClick={handleActionClick}>View more details</Toast.Link>
   </Toast.Body>
 	<Toast.CloseIcon aria-label="Close" onClick={handleClose} />
 </Toast>
 ```
 
-🤖 The codemod will convert the `Toast` into a compound component with it's sub components having
-the correct props.
+🤖 The codemod will rewrite your usages of the previous `Toast` in [Main](#main) to use the compound
+component API of the new `Toast` in [Main](#main). `mode` will be set to `dialog` if the `Toast` previously
+used `actionText` or `onActionClick`. The codemod will also update imports from the [Labs](#labs) `Toast` to
+instead import from [Main](#main).
 
-> **Note**: If your Toast is a warning of some kind, you'll have to manually set the `mode` to
-> `alert`.
+> **Note:** You will manually need to set `mode` to `alert` if your `Toast` conveys urgent and
+> important information such as an error.
 
 ## Utility Updates
 
-### focusRing
-
-We're removing memoization from focus ring. The `memoize` argument passed to `focusRing` is no
-longer valid and we've removed the exported `memoizedFocusRing`. There is no codemod for this
-change. We couldn't find any example of `memoize` or `memoizedFocusRing` being used.
-
 ### useTheme and getTheme
 
-We've updated `useTheme` by adding error handling if this hook has been used outside a functional
-component. Also, `getTheme` method has been added to access a theme from `styled` or class
-components instead of `useTheme`.
+**PR:** [#2120](https://github.com/Workday/canvas-kit/pull/2120)
 
-### useCanvasTheme and getCanvasTheme
-
-`useCanvasTheme` and `getCanvasTheme` have been removed and can be safely replaced by `useTheme`
-and `getTheme`.
+We've added error handling to `useTheme` if it's been used outside a functional component. We've
+also added `getTheme` to provide access to a theme from `styled` or class components instead of
+`useTheme`.
 
 ### useThemedRing
 
-We've promoted `useThemedRing` from our Labs package to our Main package. You can use this utility
-to theme focus rings.
+**PR:** [#2119](https://github.com/Workday/canvas-kit/pull/2119)
+
+We've promoted `useThemedRing` from [Labs](#labs) to [Main](#main). `useThemedRing` allows you to theme focus rings.
 
 🤖 The codemod will update the import for this utility.
 
-### useThemeRTL
+## Glossary
 
-We've [soft-deprecated](#soft-deprecation) `useThemeRTL` from our Labs package. Although you may
-still use this utility, we encourage consumers to use
-[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties).
+### Main
 
-## Token Updates
+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.
 
-### Depth
+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.
 
-In v7, we released an update to our depth tokens that was too bold and harsh for web applications.
-We've modified the depth token styles to be more subtle and improve visual design. This change
-affects all components which use depth tokens including `Card`, `Toast`, `Dialog`, `Popup`, `Modal`,
-and `Menu`. We have not changed which depth values each component references (i.e., `Card` remains
-at `depth[1]`).
+---
+
+### 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "9.0.0-alpha.382-next.2+5edca312",
+  "version": "9.0.0-alpha.384-next.3+e5b26417",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -44,9 +44,9 @@
   "dependencies": {
     "@emotion/styled": "^11.6.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^9.0.0-alpha.382-next.2+5edca312",
-    "@workday/canvas-kit-preview-react": "^9.0.0-alpha.382-next.2+5edca312",
-    "@workday/canvas-kit-react": "^9.0.0-alpha.382-next.2+5edca312",
+    "@workday/canvas-kit-labs-react": "^9.0.0-alpha.384-next.3+e5b26417",
+    "@workday/canvas-kit-preview-react": "^9.0.0-alpha.384-next.3+e5b26417",
+    "@workday/canvas-kit-react": "^9.0.0-alpha.384-next.3+e5b26417",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "markdown-to-jsx": "^6.10.3",
     "ts-node": "^10.9.1"
@@ -57,5 +57,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "4.2"
   },
-  "gitHead": "5edca312f27bb6df43083e778e7c7eb06f34e655"
+  "gitHead": "e5b264177aabd434723720e16048673c3916b156"
 }