@workday/canvas-kit-docs 15.0.0-alpha.1301-next.0 → 15.0.0-alpha.1326-next.0

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "14.0.17",
-    "@workday/canvas-kit-preview-react": "14.0.17",
-    "@workday/canvas-kit-react": "14.0.17",
-    "@workday/canvas-kit-react-fonts": "^14.0.17",
-    "@workday/canvas-kit-styling": "14.0.17",
+    "@workday/canvas-kit-labs-react": "14.1.10",
+    "@workday/canvas-kit-preview-react": "14.1.10",
+    "@workday/canvas-kit-react": "14.1.10",
+    "@workday/canvas-kit-react-fonts": "^14.1.10",
+    "@workday/canvas-kit-styling": "14.1.10",
     "@workday/canvas-system-icons-web": "3.0.36",
     "@workday/canvas-tokens-web": "3.1.2"
   },

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "14.0.17",
-    "@workday/canvas-kit-preview-react": "14.0.17",
-    "@workday/canvas-kit-react": "14.0.17",
-    "@workday/canvas-kit-react-fonts": "^14.0.17",
-    "@workday/canvas-kit-styling": "14.0.17",
+    "@workday/canvas-kit-labs-react": "14.1.10",
+    "@workday/canvas-kit-preview-react": "14.1.10",
+    "@workday/canvas-kit-react": "14.1.10",
+    "@workday/canvas-kit-react-fonts": "^14.1.10",
+    "@workday/canvas-kit-styling": "14.1.10",
     "@workday/canvas-system-icons-web": "3.0.36",
     "@workday/canvas-tokens-web": "3.1.2"
   },

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

@@ -38,6 +38,7 @@ visual reference of what's changed.**
   - [Expandable](#expandable)
   - [Hyperlink and External Hyperlink](#hyperlink-and-external-hyperlink)
   - [Loading Dots](#loading-dots)
+  - [Modals and Dialogs](#modals-and-dialogs)
   - [Pill (Preview)](#pill-preview)
   - [Search Form (Labs)](#search-form-labs-)
   - [Status Indicator (Preview)](#status-indicator-preview-)
@@ -55,7 +56,7 @@ visual reference of what's changed.**
   - [Deprecated Buttons](#deprecated-buttons)
   - [Input Provider](#input-provider)
   - [Menu (Preview)](#menu-preview)
-  - [readyOnlyPillStencil and removeablePillStencil](#readonlypillstencil-and-removeablepillstencil)
+  - [readOnlyPillStencil and removeablePillStencil](#readonlypillstencil-and-removeablepillstencil)
   - [Text Area (Labs)](#text-area)
   - [Text Input (Labs)](#text-input)
 - [Troubleshooting](#troubleshooting)
@@ -629,7 +630,7 @@ provide a value for the `name` prop.
 The `Pill` component no longer supports `default` as a value for the `variant` prop. If the
 `variant` prop is not provided, the component will use its default styling.
 
-`readyOnlyPillStencil` and `removeablePillStencil` have been removed. Please use `pillStencil`
+`readOnlyPillStencil` and `removeablePillStencil` have been removed. Please use `pillStencil`
 instead.
 
 **Before in v13**
@@ -650,6 +651,36 @@ instead.
 </Pill>
 ```
 
+### Modals and Dialogs
+
+Previously, the `usePopupStack` hook created a CSS class name that was passed to our Popups. We attached those theme styles to that class name. This allowed the theme to be available in our Popups. But it also created a cascade barrier that blocked the global theme from being applied to our Popup components.
+Because we now use global CSS variables, we no longer need this class name to provide the global theme to Popups. But we have to remove this generated class name to allow the global theme to be applied to Popups.
+
+
+> **Important:** Passing a `theme` to the `CanvasProvider` **will not** theme components in Modals
+> and Dialogs. You can either pass a `className` or define CSS variables at the root.
+
+**Before in v13**
+
+```tsx
+// When passing a theme to the Canvas Provider, the `usePopupStack` would grab the theme and generate a class to forward the theme to Modals and Dialogs. This would create a cascade barrier for any CSS variables deinfed at the root.
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'blue'}}}}}>
+  <Modal>//... rest of modal code</Modal>
+</CanvasProvider>
+```
+
+**After in v14**
+
+```tsx
+// If you wish to still theme you application and Modals, you can either define the CSS variables at the root level of your application or define a className and pass it to the CanvasProvider.
+:root {
+ --cnvs-brand-primary-base: blue;
+}
+
+<CanvasProvider>
+  <Modal>//... rest of modal code</Modal>
+</CanvasProvider>
+```
 ### Search Form (Labs) 🚨
 
 **PR:** [#3303](https://github.com/Workday/canvas-kit/pull/3303)
@@ -908,9 +939,9 @@ const buttonStyles = createStyles({
 We've removed `Menu` from `@workday/canvas-kit-preview-react`. Please use
 [Menu](/components/popups/menu/) from `@workday/canvas-kit-react` instead.
 
-### readyOnlyPillStencil and removeablePillStencil
+### readOnlyPillStencil and removeablePillStencil
 
-The `readyOnlyPillStencil` and `removeablePillStencil` utilities have been removed from the Pill
+The `readOnlyPillStencil` and `removeablePillStencil` utilities have been removed from the Pill
 package. Please use `pillStencil` instead.
 
 ### Text Area (Preview)
@@ -966,7 +997,7 @@ import {TextInput} from '@workday/canvas-kit-preview-react/text-input';
 **After in v14**
 
 ```tsx
-import {TextArea} from '@workday/canvas-kit-react/text-input';
+import {TextArea} from '@workday/canvas-kit-react/text-area';
 import {FormField} from '@workday/canvas-kit-react/form-field';
 
 <FormField>

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

@@ -0,0 +1,8 @@
+# Canvas Kit 15.0 Upgrade Guide
+
+This guide contains an overview of the changes in Canvas Kit v15. Please
+[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
+any questions.
+
+
+More to come soon...

package/dist/mdx/preview-react/avatar/examples/Decorative.tsx

@@ -1,6 +1,6 @@
 import {Avatar} from '@workday/canvas-kit-preview-react/avatar';
 // @ts-ignore
-import nicholasAvatar from './nicholas-avatar.png';
+import nicholasAvatar from './nicholas-avatar.jpg';
 import {createStyles} from '@workday/canvas-kit-styling';
 import {Text} from '@workday/canvas-kit-react/text';
 import {system} from '@workday/canvas-tokens-web';

package/dist/mdx/react/_examples/mdx/ContextualHelp.mdx

@@ -0,0 +1,36 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import ContextualHelpTooltip from './examples/ContextualHelp/ContextualHelpTooltip';
+import ContextualHelpDialogFocusRedirect from './examples/ContextualHelp/ContextualHelpDialogFocusRedirect';
+import ContextualHelpDialogFocusTrap from './examples/ContextualHelp/ContextualHelpDialogFocusTrap';
+
+
+
+## Contextual Help
+
+### Tooltip
+A Canvas Kit `Tooltip` can be used to provide additional information about why an element is disabled. 
+We should not, however, put one directly onto a disabled element because disabled elements do not receive focus
+(meaning the tooltip content is not accessible to keyboard users). Instead, we should provide a button next to the disabled
+element and apply the `Tooltip` to the button.
+
+**Note: We should avoid passing the `type` prop to the `Tooltip`. The default behavior is to assign an `aria-label` to the button
+(which is what we want)**
+<ExampleCodeBlock code={ContextualHelpTooltip} />
+
+### Contextual Help Popup Without Focus Trap
+If one would like to provide a bit more content than a `Tooltip` will allow (such as buttons or links) a popup should be used.
+In this example, a `Dialog` is used in conjunction with the `useFocusRedirect` hook to display some text and a link. It will
+not trap focus; instead, it will close and focus the next element if the user tabs out or clicks away. A `Tooltip` is still
+used on the `Dialog.Target` component so that it remains accessible for screen readers.
+
+`Dialog` inserts an invisible `<div>` element right after the button with an `aria-owns` attribute pointing to the 
+`Dialog.Card`. This allows screen readers to read the popup contents in a logical order with the target. In other words, the 
+screen reader will announce the `Dialog` right after the open button instead of out of order.
+
+Additionally, we apply `aria-describedby` to our `Dialog.Target` to associate it with the `FormField.Label`.
+<ExampleCodeBlock code={ContextualHelpDialogFocusRedirect} />
+
+### Contextual Help Dialog With Focus Trap
+The `useFocusTrap` hook can be used in contextual help where trapping focus within the `Dialog` is the goal. In this case, 
+focus will remain in the `Dialog` until it is closed. This example is otherwise identical to the one above.
+<ExampleCodeBlock code={ContextualHelpDialogFocusTrap} />

package/dist/mdx/react/_examples/mdx/examples/ContextualHelp/ContextualHelpDialogFocusRedirect.tsx

@@ -0,0 +1,75 @@
+import {Hyperlink, TertiaryButton} from '@workday/canvas-kit-react/button';
+import {infoIcon} from '@workday/canvas-system-icons-web';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {system} from '@workday/canvas-tokens-web';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {Dialog, useDialogModel} from '@workday/canvas-kit-react/dialog';
+import {
+  useCloseOnEscape,
+  useCloseOnOutsideClick,
+  useFocusRedirect,
+  useInitialFocus,
+  useReturnFocus,
+} from '@workday/canvas-kit-react/popup';
+import {useUniqueId} from '@workday/canvas-kit-react/common';
+
+const containerStyles = createStyles({
+  flexDirection: 'row',
+  gap: system.space.x2,
+});
+
+const labelStyles = createStyles({
+  minWidth: 'unset',
+  width: '100%',
+});
+
+export function ContextualHelpDialogFocusRedirect() {
+  const dialogModel = useDialogModel();
+  useCloseOnOutsideClick(dialogModel);
+  useCloseOnEscape(dialogModel);
+  useInitialFocus(dialogModel);
+  useFocusRedirect(dialogModel);
+  useReturnFocus(dialogModel);
+
+  const labelId = useUniqueId();
+
+  return (
+    <Flex>
+      <FormField>
+        <Flex className={containerStyles}>
+          <FormField.Label className={labelStyles} id={labelId}>
+            Country
+          </FormField.Label>
+          <Dialog model={dialogModel}>
+            <Tooltip title="More Info">
+              <Dialog.Target
+                as={TertiaryButton}
+                size="small"
+                icon={infoIcon}
+                aria-describedby={labelId}
+              />
+            </Tooltip>
+            <Dialog.Popper placement="right">
+              <Dialog.Card>
+                <Dialog.CloseIcon aria-label="Close" />
+                <Dialog.Heading paddingTop={system.space.x6}>Information</Dialog.Heading>
+                <Dialog.Body>
+                  This dialog does not trap focus, so tabbing out of it will cause it to close
+                </Dialog.Body>
+                <Flex gap={system.space.x4} padding={system.space.x2} marginTop={system.space.x2}>
+                  <Hyperlink href="/">Link</Hyperlink>
+                </Flex>
+              </Dialog.Card>
+            </Dialog.Popper>
+          </Dialog>
+        </Flex>
+        <FormField.Field>
+          <FormField.Input as={TextInput} />
+        </FormField.Field>
+      </FormField>
+    </Flex>
+  );
+}

package/dist/mdx/react/_examples/mdx/examples/ContextualHelp/ContextualHelpDialogFocusTrap.tsx

@@ -0,0 +1,77 @@
+import {Hyperlink, TertiaryButton} from '@workday/canvas-kit-react/button';
+import {infoIcon} from '@workday/canvas-system-icons-web';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {system} from '@workday/canvas-tokens-web';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {
+  useCloseOnEscape,
+  useCloseOnOutsideClick,
+  useFocusTrap,
+  useInitialFocus,
+  usePopupModel,
+  useReturnFocus,
+} from '@workday/canvas-kit-react/popup';
+import {Dialog} from '@workday/canvas-kit-react/dialog';
+import {useUniqueId} from '@workday/canvas-kit-react/common';
+
+const containerStyles = createStyles({
+  flexDirection: 'row',
+  gap: system.space.x2,
+});
+
+const labelStyles = createStyles({
+  minWidth: 'unset',
+  width: '100%',
+});
+
+export function ContextualHelpDialogFocusTrap() {
+  const dialogModel = usePopupModel();
+  useCloseOnOutsideClick(dialogModel);
+  useCloseOnEscape(dialogModel);
+  useInitialFocus(dialogModel);
+  useFocusTrap(dialogModel);
+  useReturnFocus(dialogModel);
+
+  const labelId = useUniqueId();
+
+  return (
+    <Flex>
+      <FormField>
+        <Flex className={containerStyles}>
+          <FormField.Label className={labelStyles} id={labelId}>
+            Name
+          </FormField.Label>
+          <Dialog model={dialogModel}>
+            <Tooltip title="More Info">
+              <Dialog.Target
+                as={TertiaryButton}
+                size="small"
+                icon={infoIcon}
+                aria-describedby={labelId}
+              />
+            </Tooltip>
+            <Dialog.Popper placement="right">
+              <Dialog.Card>
+                <Dialog.CloseIcon aria-label="Close" />
+                <Dialog.Heading paddingTop={system.space.x6}>Information</Dialog.Heading>
+                <Dialog.Body>
+                  This dialog traps focus. Focus will only return to the rest of the page when the
+                  dialog is closed
+                </Dialog.Body>
+                <Flex gap={system.space.x4} padding={system.space.x2} marginTop={system.space.x2}>
+                  <Hyperlink href="/">Link</Hyperlink>
+                </Flex>
+              </Dialog.Card>
+            </Dialog.Popper>
+          </Dialog>
+        </Flex>
+        <FormField.Field>
+          <FormField.Input as={TextInput} />
+        </FormField.Field>
+      </FormField>
+    </Flex>
+  );
+}

package/dist/mdx/react/_examples/mdx/examples/ContextualHelp/ContextualHelpTooltip.tsx

@@ -0,0 +1,42 @@
+import {PrimaryButton, TertiaryButton} from '@workday/canvas-kit-react/button';
+import {infoIcon} from '@workday/canvas-system-icons-web';
+import {Tooltip} from '@workday/canvas-kit-react/tooltip';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+import React from 'react';
+
+const outerContainerStyles = createStyles({
+  flexDirection: 'column',
+});
+
+const buttonContainerStyles = createStyles({
+  flexDirection: 'row',
+  gap: system.space.x1,
+  alignItems: 'center',
+});
+
+export function ContextualHelpTooltip() {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(event.target.value);
+  };
+
+  return (
+    <Flex className={outerContainerStyles}>
+      <FormField isRequired>
+        <FormField.Label>Favorite Food</FormField.Label>
+        <FormField.Input as={TextInput} onChange={handleChange}></FormField.Input>
+      </FormField>
+      <Flex className={buttonContainerStyles}>
+        <PrimaryButton disabled={!value}>Submit</PrimaryButton>
+        <Tooltip title="All fields must be filled before submitting" placement="right">
+          <TertiaryButton icon={infoIcon} size="small" aria-label="Info" disabled={!!value} />
+        </Tooltip>
+      </Flex>
+    </Flex>
+  );
+}

package/dist/mdx/react/common/mdx/Theming.mdx

@@ -134,6 +134,36 @@ const themedBrand = createStyles({
 </CanvasProvider>
 ```
 
+### Theming Modals and Dialogs
+
+Previously, the `usePopupStack` hook created a CSS class name that was passed to our Popups. We attached those theme styles to that class name. This allowed the theme to be available in our Popups. But it also created a cascade barrier that blocked the global theme from being applied to our Popup components.
+Because we now use global CSS variables, we no longer need this class name to provide the global theme to Popups. But we have to remove this generated class name to allow the global theme to be applied to Popups.
+
+> **Important:** Passing a `theme` to the `CanvasProvider` **will not** theme components in Modals
+> and Dialogs. You can either pass a `className` or define CSS variables at the root.
+
+**Before in v13**
+
+```tsx
+// When passing a theme to the Canvas Provider, the `usePopupStack` would grab the theme and generate a class to forward the theme to Modals and Dialogs. This would create a cascade barrier for any CSS variables deinfed at the root.
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'blue'}}}}}>
+  <Modal>//... rest of modal code</Modal>
+</CanvasProvider>
+```
+
+**After in v14**
+
+```tsx
+// If you wish to still theme you application and Modals, you can either define the CSS variables at the root level of your application or define a className and pass it to the CanvasProvider.
+:root {
+ --cnvs-brand-primary-base: blue;
+}
+
+<CanvasProvider>
+  <Modal>//... rest of modal code</Modal>
+</CanvasProvider>
+```
+
 ## CSS Token Structure
 
 Canvas Kit provides three layers of CSS variables.

package/dist/mdx/style-props/STYLE_PROPS.mdx

@@ -47,7 +47,7 @@ with props.
   <InformationHighlight.Body>
     As we transition away from Emotion's runtime costs, we advise to move away from using style props. Please use our [styling utilities](https://workday.github.io/canvas-kit/?path=/docs/styling-getting-started-overview--docs) instead. For more information on this change, view our discussion on the [Future of Styling](https://github.com/Workday/canvas-kit/discussions/2265).
 
-    You can use `14.1` codemod to automatic migration to `cs` prop. [More about codemods](http://localhost:9001/?path=/docs/guides-codemods--docs)
+    You can use `14.1` codemod to automatic migration to `cs` prop. [Migration Docs](https://workday.github.io/canvas-kit/?path=/docs/guides-codemods--docs)
 
   </InformationHighlight.Body>
 </InformationHighlight>

package/dist/mdx/style-props/stylePropsMigrationCodemod.mdx

@@ -0,0 +1,99 @@
+import {InformationHighlight} from '@workday/canvas-kit-preview-react/information-highlight';
+import {StorybookStatusIndicator, DownloadLLMFile} from '@workday/canvas-kit-docs';
+
+
+# Canvas Kit Style Props Migration Codemod
+
+This codemod helps migrate style props to `cs` prop. It also automatically transforms token usage in
+your codebase to use the new token system.
+
+## Important Notes
+
+- **Run on Small Batches**: We recommend running the codemod on a small number of files in batches
+  instead of your entire repository all at once. This makes the changes easier to review and allows
+  you to catch issues more quickly with less frustration.
+- **Codemod Limitations**: The codemod does not cover every possible token usage or migration
+  scenario. Please review the codemod's changes and be prepared to update style props as needed.
+  Some manual changes will be required, especially for:
+  - Custom or dynamic style usage
+  - Updating documentation, comments, or non-code files
+
+## Required Dependencies
+
+The codemod requires the following packages to be installed:
+
+- `@workday/canvas-kit-styling`
+- `@workday/canvas-tokens-web`
+
+## Installation
+
+You can run the codemod using npx:
+
+```sh
+npx @workday/canvas-kit-codemod v14.1 [path]
+```
+
+Or install the package and run it directly. But remember to uninstall the package after you have
+completed the upgrade.
+
+```sh
+yarn add @workday/canvas-kit-codemod
+canvas-kit-codemod v14.1 [path]
+```
+
+> Note: These codemods only work 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 its resulting formatting
+> (spacing, quotes, etc.) may not match your project's styling.
+
+## What This Codemod Does
+
+The Canvas Kit codemod automates the migration from **deprecated style props** and **Emotion-based
+styling** to the new **Canvas Kit Styling** system. It is designed to handle the majority of
+migration cases safely and efficiently, minimizing manual refactoring.
+
+### Goals
+
+- Accelerate migration to `@workday/canvas-kit-styling`
+- Maintain visual parity between old and new implementations
+- Reduce developer effort and manual code changes
+- Ensure consistent use of `cs` prop
+
+## What to Expect
+
+After running the codemod, your code will:
+
+1. Use the new `cs` props in CK components instead of style props
+2. Transform token names used as style prop value to a new v3 token
+3. Have correct token import
+
+## Example Transformations
+
+### Before
+
+```typescript
+import {Flex} from '@workday/canvas-kit-react/layout';
+
+<Flex depth={1} marginX={10} background="frenchVanilla100" />;
+```
+
+### After
+
+```typescript
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {system} from '@workday/canvas-tokens-web';
+
+<Flex
+  cs={{
+    boxShadow: system.depth[1],
+    marginInline: 10,
+    background: system.color.bg.default,
+  }}
+/>;
+```
+
+## What the Codemod Does Not Do
+
+The codemod will not hoist your styles to the top of the file. While we don't expect you to do this
+immediately, we strongly encourage you to do this in the future and at a gradual pace.