@workday/canvas-kit-docs 14.0.0-alpha.1254-next.0 → 14.0.0-alpha.1256-next.0

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

@@ -11,7 +11,8 @@ styling updates to our components.
 
 **Please consult our [v14 Visual Changes](/help/upgrade-guides/canvas-v14-upgrade-guide/#tab=visual-changes) page for a visual reference of what's changed.**
 
-> **Note:** While v14 does not require an upgrade to our v3 tokens, we strongly advise to upgrade to the latest to ensure proper branding.
+> **Note:** While v14 does not require an upgrade to our v3 tokens, we strongly advise to upgrade to
+> the latest to ensure proper branding.
 
 ## Table of contents
 
@@ -34,6 +35,7 @@ styling updates to our components.
   - [Pill (Preview)](#pill-preview)
   - [Search Form (Labs)](#searchform-)
   - [Status Indicator (Preview)](#status-indicator-preview-)
+  - [Icons](#icons)
 - [Deprecations](#deprecations)
   - [Avatar (Main)](#avatar-in-main)
   - [Combobox (Labs)](#combobox-labs)
@@ -42,6 +44,7 @@ styling updates to our components.
   - [Segmented Control (Main)](#segmented-control-main)
   - [Side Panel (Main)](#side-panel-main)
   - [Tokens](#tokens)
+  - [useIsRTL](#useisrtl)
 - [Removals](#removals)
   - [Deprecated Buttons](#deprecated-buttons)
   - [Input Provider](#input-provider)
@@ -119,8 +122,8 @@ yarn remove @workday/canvas-kit-codemod
 ## Tokens
 
 Canvas Kit v14 now uses `@workday/canvas-tokens-web` v3, which introduces new color palettes and
-deprecates the old "fruity" color names (for example, use `red` instead of `cinnamon`, `blue` instead
-of `blueberry`, and `green` instead of `greenApple`). We strongly recommend upgrading to
+deprecates the old "fruity" color names (for example, use `red` instead of `cinnamon`, `blue`
+instead of `blueberry`, and `green` instead of `greenApple`). We strongly recommend upgrading to
 `@workday/canvas-tokens-web` v3, as using older versions will not match the new brand guidelines or
 color system. Although this dependency upgrade is not required, we've offered migration guides and
 codemods separately from the v14 upgrade so that teams can upgrade when they can.
@@ -145,7 +148,8 @@ Follow these guides to migrate:
 To better align with the brand refresh, Alert and Warning states are being renamed to Caution for
 better semantics.
 
-This change mostly affects how you pass an error state to our input components. In most cases, our input components should be used with our `FormField` component to ensure correct accessibility.
+This change mostly affects how you pass an error state to our input components. In most cases, our
+input components should be used with our `FormField` component to ensure correct accessibility.
 
 **Before in v13**
 
@@ -171,7 +175,8 @@ This change mostly affects how you pass an error state to our input components.
 </FormField>
 ```
 
-If you are using the error type either from our `Common` package or the one exposed from the component, the naming has also changed.
+If you are using the error type either from our `Common` package or the one exposed from the
+component, the naming has also changed.
 
 **Before in v13**
 
@@ -228,8 +233,7 @@ our CSS variables. Instead of generating a palette and shifting the brightness a
 
 Prior to v14, `CanvasProvider` created a [cascade barrier](/get-started/for-developers/theming/overview/#what-is-a-cascade-barrier), which redefined brand CSS variables under a class and created a higher specificity. This made it difficult to override brand tokens in certain scenarios. v14 removes that barrier.
 
-**Before in v13**
-In v13, the `useTheme` hook would call `createCanvasTheme` which generated a
+**Before in v13** In v13, the `useTheme` hook would call `createCanvasTheme` which generated a
 palette given a `main` color via `chroma.js`.
 
 ```tsx
@@ -287,6 +291,17 @@ The reason for this change is to ensure that the CSS variables properly cascade
 Before in v13, the `CanvasProvider` would add the brand tokens under a class name, creating a higher
 specificity.
 
+
+### useIsRTL
+
+**PR:** [#3480](https://github.com/Workday/canvas-kit/pull/3477)
+
+The `useIsRTL` hook has been deprecated. Please use
+[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
+for styling, `isElementRTL` for event handlers, and `shouldMirrorInRTL` for icons. If you need
+`useIsRTL` for any other reason, please file a issue. See the [Icons](#icons) section for more
+details on the new `shouldMirrorInRTL` prop.
+
 ## Component Updates
 
 ### Avatar (Preview)
@@ -347,9 +362,12 @@ revolve around the use of our new brand colors. For a better guide on what has c
 tokens, please view the Tokens v3.0.0
 [Upgrade Guide](https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v3-overview--docs).
 
+
 The following components have been updated (**see [v14 Visual Changes](/help/upgrade-guides/canvas-v14-upgrade-guide/#tab=visual-changes) for a visual reference of the updates**):
 
-- `Breadcrumbs` [#3270](https://github.com/Workday/canvas-kit/pull/3270),[#3447](https://github.com/Workday/canvas-kit/pull/3447)
+
+- `Breadcrumbs`
+  [#3270](https://github.com/Workday/canvas-kit/pull/3270),[#3447](https://github.com/Workday/canvas-kit/pull/3447)
 - `Buttons` [#3394](https://github.com/Workday/canvas-kit/pull/3394)
 - `ColorPicker` (Main) [#3307](https://github.com/Workday/canvas-kit/pull/3307)
 - `ColorPicker` (preview) [#3307](https://github.com/Workday/canvas-kit/pull/3307)
@@ -369,9 +387,9 @@ The following components have been updated (**see [v14 Visual Changes](/help/upg
 
 **Breaking Changes**
 
-- The `TertiaryButton` component no longer supports the `isThemable` prop. To customize the appearance
-  of `TertiaryButton`, use the `cs` prop for custom styles or the `colors` prop for palette-based
-  color overrides.
+- The `TertiaryButton` component no longer supports the `isThemable` prop. To customize the
+  appearance of `TertiaryButton`, use the `cs` prop for custom styles or the `colors` prop for
+  palette-based color overrides.
 - The shape of `TertiaryButton` has changed to have rounded corners, aligning with other buttons and
   our new brand direction.
 
@@ -401,10 +419,10 @@ visual hierarchy and more flexible styling options. The following changes have b
 
 #### Default Card No Longer Has a Box Shadow
 
-The default `Card` variant no longer includes a box shadow, creating a cleaner, flatter appearance that
-aligns with our new brand's emphasis on simplicity and clarity. This is a **visual breaking change**
-that may affect your application's visual hierarchy. If your design requires shadow you can add it
-through the `cs` prop.
+The default `Card` variant no longer includes a box shadow, creating a cleaner, flatter appearance
+that aligns with our new brand's emphasis on simplicity and clarity. This is a **visual breaking
+change** that may affect your application's visual hierarchy. If your design requires shadow you can
+add it through the `cs` prop.
 
 **Before in v13**
 
@@ -415,8 +433,7 @@ through the `cs` prop.
 </Card>
 ```
 
-**After in v14**
-Only do this if you need a shadow. Otherwise, adhere to the default styling.
+**After in v14** Only do this if you need a shadow. Otherwise, adhere to the default styling.
 
 ```tsx
 import {system} from '@workday/canvas-tokens-web';
@@ -604,7 +621,7 @@ const customTheme = {
   placeholderColor: colors.frenchVanilla100,
   placeholderColorFocus: colors.blackPepper400,
   boxShadow: ['10px 5px 5px red', '60px -16px teal'],
-  boxShadowFocus: ['10px 5px 5px red', '60px -16px teal']
+  boxShadowFocus: ['10px 5px 5px red', '60px -16px teal'],
 } as SearchThemeAttributes;
 
 <SearchForm
@@ -612,7 +629,7 @@ const customTheme = {
   autocompleteItems={menuItems}
   onInputChange={filterMenuItems}
   onSubmit={handleSubmit}
-/>
+/>;
 ```
 
 **After in v14**
@@ -632,7 +649,7 @@ const customTheme = {
   autocompleteItems={menuItems}
   onInputChange={filterMenuItems}
   onSubmit={handleSubmit}
-/>
+/>;
 ```
 
 - `SearchTheme` enum type has been updated to have string values `light`, `dark` and `transparent`.
@@ -677,6 +694,34 @@ deprecated. Use `StatusIndicatorProps['variant']` instead.
 <StatusIndicator variant="neutral" />
 ```
 
+### Icons
+
+**PR:** [#3477](https://github.com/Workday/canvas-kit/pull/3477)
+
+`shouldMirrorInRTL` has been added to `Icon` components (`SVG`, `SystemIcon`, `AccentIcon`,
+`AppletIcon`, `SystemIconCircle`, `AIIngressButton`, `BaseButton.Icon`, `Button`,
+`ToolbarDropdownButton`, `ToolbarIconButton`, `ButtonLabelIcon`, `PrimaryButton`, `SecondaryButton`,
+and `TertiaryButton`). This is used to mirror the icon when the content direction is `rtl`. This is
+meant to replace `useIsRTL` combined with the `shouldMirror` prop. Instead of getting the content
+direction from JavaScript and passing to components, you can now pass `shouldMirrorInRTL={true}` to
+the component which will mirror the icon only when the content direction is `rtl`.
+
+**Before in v13**
+
+```tsx
+<IconComponent shouldMirror={useIsRTL()} />
+```
+
+**After in v14**
+
+```tsx
+<IconComponent shouldMirrorInRTL />
+```
+
+You can still use `shouldMirror` if you intend to always mirror an icon. This is less ideal because
+you cannot use `shouldMirror` and `shouldMirrorInRTL` together. The icon will be mirrored regardless
+of content direction if both props are used.
+
 ## Deprecations
 
 We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) JSDoc tag to code we plan to remove
@@ -708,7 +753,7 @@ import { Avatar } from '@workday/canvas-kit-react/avatar';
 import {Avatar} from '@workday/canvas-kit-preview-react/avatar';
 // name is used as a fallback if the image url is broken or still loading
 // variant defines the color of the Avatar
-<Avatar name="John Doe" size="extraExtraLarge" variant="teal" url={yourImageUrl} />
+<Avatar name="John Doe" size="extraExtraLarge" variant="teal" url={yourImageUrl} />;
 ```
 
 If you need to render a `button` element use the `BaseAvatar` component.
@@ -724,7 +769,7 @@ import {BaseAvatar} from '@workday/canvas-kit-preview-react/avatar';
   onClick={() => console.log('Avatar clicked')}
 >
   <BaseAvatar.Name name="John Doe" />
-</BaseAvatar>
+</BaseAvatar>;
 ```
 
 ### Combobox (Labs)
@@ -785,8 +830,8 @@ system supported this for quite some time, but with the advancement in theming,
 and our flexibility, it is time for us to finally remove this component. This component has served
 as a reminder of how far we've come and we're thankful for this change.
 
-Although unlikely, if you were using `DeprecatedButton` please use our flexible
-and themable buttons like `PrimaryButton`, `SecondaryButton` or `TertiaryButton`.
+Although unlikely, if you were using `DeprecatedButton` please use our flexible and themable buttons
+like `PrimaryButton`, `SecondaryButton` or `TertiaryButton`.
 
 ### Input Provider
 
@@ -798,8 +843,8 @@ browser heuristics to determine when an element should receive visual focus styl
 information, please view the
 [MDN docs on `:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible).
 
-If you are trying to apply focus styles to our components, we strongly advise using the `:focus-visible`
-pseudo selector.
+If you are trying to apply focus styles to our components, we strongly advise using the
+`:focus-visible` pseudo selector.
 
 ```tsx
 import {createStyles} from '@workday/canvas-kit-styling'
@@ -901,22 +946,26 @@ import {FormField} from '@workday/canvas-kit-react/form-field';
 
 ### Common Issues
 
-- **Dependency Conflicts**: When upgrading to the latest major version of Canvas Kit, all related Canvas Kit packages should
-  be updated at the same time:
+- **Dependency Conflicts**: When upgrading to the latest major version of Canvas Kit, all related
+  Canvas Kit packages should be updated at the same time:
+
   - `"@workday/canvas-kit-react": "^13.5.6"` → `"@workday/canvas-kit-react": "^14.0.0"`
   - `"@workday/canvas-kit-styling": "^13.5.6"` → `"@workday/canvas-kit-styling": "^14.0.0"`
   - `"@workday/canvas-kit-preview-react": "^13.5.6"` →
     `"@workday/canvas-kit-preview-react": "^14.0.0"`
   - `"@workday/canvas-kit-labs-react": "^13.5.6"` → `"@workday/canvas-kit-labs-react": "^14.0.0"`
 
-- **Token Issues**: Our components rely on the `@workday/canvas-tokens-web` package which provides our CSS variables
-  and ensures the correct styling of our components. Make sure to upgrade to the latest version of
-  Canvas Tokens Web and install it correctly. For more information,
+- **Token Issues**: Our components rely on the `@workday/canvas-tokens-web` package which provides
+  our CSS variables and ensures the correct styling of our components. Make sure to upgrade to the
+  latest version of Canvas Tokens Web and install it correctly. For more information,
   [view our docs](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
 
-- **Color Discrepancies**: If you notice visual differences after upgrading, this may be due to the change from `chroma.js` to `oklch` color generation. Consider providing explicit color values in your theme configuration.
+- **Color Discrepancies**: If you notice visual differences after upgrading, this may be due to the
+  change from `chroma.js` to `oklch` color generation. Consider providing explicit color values in
+  your theme configuration.
 
-- **Build Errors**: If you encounter build errors after running the codemod, ensure your linter is run as the codemod's formatting may not match your project conventions.
+- **Build Errors**: If you encounter build errors after running the codemod, ensure your linter is
+  run as the codemod's formatting may not match your project conventions.
 
 ## Glossary
 
@@ -924,10 +973,15 @@ For an overview of the different packages we provide, please view our docs
 [here](https://workday.github.io/canvas-kit/?path=/docs/guides-packages--docs).
 
 ### Main
+
 Components in the Main package are stable and ready for production use.
 
 ### Preview
-Components in the Preview package are mostly stable but may still receive breaking changes before being promoted to Main.
+
+Components in the Preview package are mostly stable but may still receive breaking changes before
+being promoted to Main.
 
 ### Labs
-Components in the Labs package are experimental and may receive significant changes or be removed entirely.
+
+Components in the Labs package are experimental and may receive significant changes or be removed
+entirely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "14.0.0-alpha.1254-next.0",
+  "version": "14.0.0-alpha.1256-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -45,10 +45,10 @@
     "@emotion/styled": "^11.6.0",
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1254-next.0",
-    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1254-next.0",
-    "@workday/canvas-kit-react": "^14.0.0-alpha.1254-next.0",
-    "@workday/canvas-kit-styling": "^14.0.0-alpha.1254-next.0",
+    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1256-next.0",
+    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1256-next.0",
+    "@workday/canvas-kit-react": "^14.0.0-alpha.1256-next.0",
+    "@workday/canvas-kit-styling": "^14.0.0-alpha.1256-next.0",
     "@workday/canvas-system-icons-web": "^3.0.35",
     "@workday/canvas-tokens-web": "3.0.0-alpha.12",
     "markdown-to-jsx": "^7.2.0",
@@ -61,5 +61,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "a177192ec9673c8f8d71ab20c7effc6382cae308"
+  "gitHead": "ecb8230f9b648de52e89d8b84340dcd31b2514b2"
 }