@workday/canvas-kit-docs 9.0.0-alpha.382-next.2 → 9.0.0-alpha.385-next.4

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

@@ -5,20 +5,28 @@ This guide contains an overview of the changes in Canvas Kit v9. Please
 any questions.
 
 - [Codemod](#codemod)
-- [Component Deprecations](#component-deprecations)
+- [New Components](#new-components)
+  - [Table](#table)
+- [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 +59,313 @@ 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
+## New Components
 
-### Deprecation Types
+### Table
 
-#### Soft Deprecation
+We've introduced a new `Table`
+[compound component](/getting-started/for-developers/resources/compound-components/) to the Preview
+package. `Table` is a compound component that is used to present information in a two-dimensional
+[table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) comprised of rows and
+columns of cells containing data.
 
-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.
+```tsx
+import {Table} from '@workday/canvas-kit-preview-react/table';
+
+export default function App() {
+  return (
+    <Table>
+      <Table.Caption>Table Caption</Table.Caption>
+      <Table.Head>
+        <Table.Row>
+          <Table.Header>Table Header</Table.Header>
+          <Table.Header>Table Header</Table.Header>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Header>Table Header</Table.Header>
+          <Table.Header>Table Header</Table.Header>
+        </Table.Row>
+        <Table.Divider />
+        <Table.Row>
+          <Table.Header>Table Header</Table.Header>
+          <Table.Cell>Table Data Cell</Table.Cell>
+        </Table.Row>
+        <Table.Divider />
+        <Table.Row>
+          <Table.Header>Table Header</Table.Header>
+          <Table.Cell>Table Data Cell</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+      <Table.Divider />
+      <Table.Footer>
+        <Table.Row>
+          <Table.Header>Table Header</Table.Header>
+          <Table.Cell>Table Data Cell</Table.Cell>
+        </Table.Row>
+      </Table.Footer>
+    </Table>
+  );
+}
+```
 
-Soft-deprecated types and utilities will also have been renamed but generally will not trigger a
-console warning.
+## Removals
 
-#### Hard Deprecation
+Removals are deletions from our codebase and you can no longer consume this component. We've either
+promoted or replaced a component or utility.
 
-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.
+### Drawer
+
+**PR:** [#1970](https://github.com/Workday/canvas-kit/pull/1970)
+
+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.
+
+> **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
+
+**PR:** [#2018](https://github.com/Workday/canvas-kit/pull/2018)
 
-<!---
-TODO: Please review this section with documenting SidePanel deprication
--->
+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.
 
-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.
+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
 
-`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.
+**PR:** [#2120](https://github.com/Workday/canvas-kit/pull/2120)
 
-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've removed `useCanvasTheme` and `getCanvasTheme`. Please use `useTheme` and `getTheme` instead.
+
+## Deprecations
+
+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
 
-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]`.
+### Depth
 
-> **Note**: If you are consuming `StackProps` for a custom component, please make sure to change the
-> `spacing` prop to the `gap` prop
+**PR:** [#2091](https://github.com/Workday/canvas-kit/pull/2091)
+
+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).
+
+This affects all buttons which extend `BaseButton`:
 
-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.
+- `PrimaryButton`
+- `SecondaryButton`
+- `TertiaryButton`
+- `DeleteButton`
+- `ToolbarDropdownButton` and `ToolbarIconButton`
+- `Pill` and `Pill.IconButton`
+- `SegmentedControl.Button` (Main)
+- `SegmentedControl.Item` (Preview)
+- `Pagination.PageButton`
 
-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.
+Any buttons which extend any of the above are affected as well.
 
-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`.
+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"`).
 
-This change affects all of our `buttons` including:
-`PrimaryButton, SecondaryButton, TertiaryButton, ToolbarButton`.
+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.
 
-If you still wish for a specific `button` within a `form` to submit, just add the attribute
-`type="submit"`.
+---
 
 ### 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)
+
+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).
 
-- 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.
+`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`.
-
-### useCanvasTheme and getCanvasTheme
+**PR:** [#2120](https://github.com/Workday/canvas-kit/pull/2120)
 
-`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/dist/mdx/preview-react/table/Table.mdx

@@ -0,0 +1,60 @@
+import {SymbolDoc, Specifications} from '@workday/canvas-kit-docs';
+import {Table} from '@workday/canvas-kit-preview-react/table';
+// examples
+import Basic from './examples/Basic';
+import BasicWithHeading from './examples/BasicWithHeading';
+import FixedColumn from './examples/FixedColumn';
+import TableWithContainer from './examples/TableWithContainer';
+
+
+# Canvas Kit Table
+
+`Table` is a simple styled compound component that renders a
+[table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table) element. It is used to
+present information in a two-dimensional table comprised of rows and columns of cells containing
+data.
+
+## Installation
+
+```sh
+yarn add @workday/canvas-kit-preview-react
+```
+
+## Usage
+
+### Basic Example
+
+Users may not want to use a `caption` so they can import
+[Heading](/docs/components-text-heading--basic) or [Text](/docs/components-text-text--basic)
+instead. This will give the user more flexibility around the customization of the title/heading of
+their table.
+
+<ExampleCodeBlock code={BasicWithHeading} />
+
+### Example with Container
+
+Users may want to have some padding around the `table` and have inset dividers for their rows. This
+showcases how a user can achieve this with creating a styled component to wrap the `table`.
+
+<ExampleCodeBlock code={TableWithContainer} />
+
+### Example with Caption
+
+We built a simple table that includes a `caption` without a Heading. A `caption` is not required but
+it is good for
+[accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#accessibility_concerns)
+purposes.
+
+<ExampleCodeBlock code={Basic} />
+
+### Fixed Column with TableContainer
+
+Users may want to have some padding surrounding their table and have a fixed column. They can use
+the `TableContainer` to wrap the `Table` component and some styles to make it so that the left
+column is fixed.
+
+<ExampleCodeBlock code={FixedColumn} />
+
+## Component API
+
+<SymbolDoc name="Table" fileName="/preview-react/" />

package/dist/mdx/preview-react/table/examples/Basic.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+
+import {Table} from '@workday/canvas-kit-preview-react/table';
+
+export default () => {
+  return (
+    <Table>
+      <Table.Caption>Coffee Drinks and Sizes</Table.Caption>
+      <Table.Head>
+        <Table.Row>
+          <Table.Header backgroundColor="soap100">Drink</Table.Header>
+          <Table.Header backgroundColor="soap100">Size</Table.Header>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>Espresso</Table.Cell>
+          <Table.Cell>1 oz</Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>Macchiato</Table.Cell>
+          <Table.Cell>2 oz Espresso</Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>Cortado</Table.Cell>
+          <Table.Cell>2 oz Espresso, 1 oz Foamed Milk</Table.Cell>
+        </Table.Row>
+        <Table.Row></Table.Row>
+        <Table.Row>
+          <Table.Cell>Cappuccino</Table.Cell>
+          <Table.Cell>2 oz Espresso, 2 oz Foamed Milk, 2 oz Steamed Milk</Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table>
+  );
+};

package/dist/mdx/preview-react/table/examples/BasicWithHeading.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+
+import {Table} from '@workday/canvas-kit-preview-react/table';
+import {Heading} from '@workday/canvas-kit-react/text';
+
+export default () => {
+  return (
+    <>
+      <Heading size="small">Pizza Toppings</Heading>
+      <Table>
+        <Table.Head>
+          <Table.Row>
+            <Table.Header backgroundColor="soap100">Toppings</Table.Header>
+            <Table.Header backgroundColor="soap100">Amount</Table.Header>
+          </Table.Row>
+        </Table.Head>
+        <Table.Body>
+          <Table.Row>
+            <Table.Cell>Pepperoni</Table.Cell>
+            <Table.Cell>2.5 oz</Table.Cell>
+          </Table.Row>
+          <Table.Row>
+            <Table.Cell>Mozzarella</Table.Cell>
+            <Table.Cell>5 oz</Table.Cell>
+          </Table.Row>
+          <Table.Row>
+            <Table.Cell>Basil</Table.Cell>
+            <Table.Cell>10 Leaves</Table.Cell>
+          </Table.Row>
+        </Table.Body>
+      </Table>
+    </>
+  );
+};