@workday/canvas-kit-mcp 13.2.41

package/dist/lib/upgrade-guides/13.0-UPGRADE-GUIDE.md

@@ -0,0 +1,516 @@
+# Canvas Kit 13.0 Upgrade Guide
+
+This guide contains an overview of the changes in Canvas Kit v13. Please
+[reach out](https://github.com/Workday/canvas-kit/issues/new?labels=bug&template=bug.md) if you have
+any questions. For common upgrade issues, please see the [Troubleshooting](#troubleshooting) section
+at the end of this guide.
+
+## Why You Should Upgrade
+
+We're really excited about the updates in Canvas Kit v13! In this release, we:
+
+- refactored components to use our Canvas tokens and styling API
+- made several accessibilty improvements
+- updated our brand logos
+- improved our infrastructure
+
+### Refactored Components to Use Our Styling API
+
+We've continued refactoring our components to use our new styling API and new Canvas tokens. This
+allows us to provide a more consistent styling experience across our components.
+
+### Updated Brand Logos
+
+As part of Workday's brand refresh, we've updated our Workday logos to align with our new brand
+design.
+
+### Improved Support for ES Modules
+
+We've updated the `jsx` flag in our `tsconfig` to `react-jsx` to provide better support for newer
+technologies including `Vite`. As part of this change, we've also updated our `react` peer
+dependencies to a minimum version of `17.0.0`.
+
+## Table of Contents
+
+- [Codemod](#codemod)
+  - [Instructions](#instructions)
+- [Component Updates](#component-updates)
+	- [Styling API and CSS Tokens](#styling-api-and-canvas-tokens-)
+	- [Avatar](#avatar-)
+	- [Expandable](#expandable-)
+	- [External Hyperlink](#external-hyperlink-)
+	- [Form Field and Form Field Group](#form-field-and-form-field-group-)
+	- [Pill (Preview)](#pill-preview-)
+	- [SidePanel (Preview)](#side-panel-preview-)
+	- [Tabs](#tabs-)
+- [Brand Refresh](#brand-refresh)
+  - [Logo Updates](#logo-updates-)
+- [Infrastructure](#infrastructure)
+	- [Supporting react-jsx](#supporting-react-jsx-)
+- [Troubleshooting](#troubleshooting)
+- [Contributors](#contributors)
+- [Glossary](#glossary)
+  - [Main](#main)
+  - [Preview](#preview)
+  - [Labs](#labs)
+
+## Codemod
+
+We've provided a [codemod](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) to
+automatically update your code to work with most of the breaking changes in v13. **Breaking changes
+handled by the codemod are marked with 🤖 in the Upgrade Guide.**
+
+### Instructions
+
+The easiest way to run our codemod is to use `npx` in your terminal.```sh
+npx @workday/canvas-kit-codemod v13 [path]
+```
+
+Be sure to provide specific directories that need to be updated via the `[path]` argument. This
+decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
+having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
+if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
+`[path]`.
+
+Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
+codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
+finished.
+
+```sh
+yarn add @workday/canvas-kit-codemod --dev
+yarn canvas-kit-codemod v13 [path]
+yarn remove @workday/canvas-kit-codemod
+```
+
+Having trouble running our codemods? View our
+[docs](https://workday.github.io/canvas-kit/?path=/docs/guides-codemods--docs) for more information!
+
+## Component Updates
+
+### Styling API and Canvas Tokens 💅
+
+Several components have been refactored to use our
+[Canvas tokens](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs) and
+[styling API](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--docs#createstyles-api).
+The React interface **has not changed**, but Canvas Tokens are now used for dynamic properties.
+
+> **Note:** These components also support our `cs` prop for styling. Learn more about styling with
+> `cs` in our
+> [documentation](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--docs#cs-prop).
+
+The following components have been updated:
+
+- `ActionBar` [#3205](https://github.com/Workday/canvas-kit/pull/3205)
+- `Banner` [#3210](https://github.com/Workday/canvas-kit/pull/3210)
+- `Expandable` [#3128](https://github.com/Workday/canvas-kit/pull/3128	)
+- `ExternalHyperlink` [#3101](https://github.com/Workday/canvas-kit/pull/3101)
+- `LoadingSparkles` [#3120](https://github.com/Workday/canvas-kit/pull/3120)
+- `Menu` [#3114](https://github.com/Workday/canvas-kit/pull/3114)
+- `Pill` [#3140](https://github.com/Workday/canvas-kit/pull/3104)
+- `Select` [#3240](https://github.com/Workday/canvas-kit/pull/3240)
+- `SidePanel (Preview)` [#3123](https://github.com/Workday/canvas-kit/pull/3123)
+- `Skeleton` [#3088](https://github.com/Workday/canvas-kit/pull/3088)
+- `Tabs` [#3119](https://github.com/Workday/canvas-kit/pull/3119)
+- `Tooltip` [#3164](https://github.com/Workday/canvas-kit/pull/3164)
+
+### Avatar 🚨
+
+**PR:** [#3231](https://github.com/Workday/canvas-kit/pull/3231)
+
+The following change has been made to `Avatar` to ensure proper accessibility.
+
+- The `altText` prop no longer has a default value of `"Avatar"` for better internalization. This
+  default phrase caused some to accidentally omit translations which caused translation issues.
+
+> **Note:** This change also impacts `Pill.Avatar` and `Expandable.Avatar`. You must provide a value
+> to `altText` to ensure proper accessibility. Our examples have been updated to reflect this
+> change.
+
+**Before in v12**
+
+```tsx
+// Avatar component always had a default altText of "Avatar"
+<Avatar as="div" />
+```
+
+**After in v13**
+
+```tsx
+// You must provide alt text to the `altText` prop. Please choose a apt description based on your `Avatar`'s usage.
+<Avatar altText="User profile avatar" as="div" />
+```
+
+### Expandable ⚡️
+
+**PR:** [#3217](https://github.com/Workday/canvas-kit/pull/3217)
+
+We've promoted `Expandable` from [Labs](#labs) to [Main](#main).
+
+**Before in v12**
+
+```tsx
+import {Expandable} from '@workday/canvas-kit-labs-react/expandable';
+```
+
+**After in v13**
+
+```tsx
+import {Expandable} from '@workday/canvas-kit-react/expandable';
+```
+
+> 🤖 The codemod will handle the change of imports as shown above.
+
+### External Hyperlink 🚨
+
+**PR:** [#3101](https://github.com/Workday/canvas-kit/pull/3101)
+
+The following change has been made to `ExternalHyperlink` to ensure proper accessibility.
+
+- The `iconLabel` prop no longer has a default value of `"Opens link in new window"`. This default
+  phrase caused some to accidentally omit translations which caused translation issues.
+
+> **Note:** While the prop is not required, you _must_ provide an `iconLabel` for `<ExternalHyperlink />` to ensure proper
+> accessibility. Our examples have been updated to reflect this change.
+
+**Before in v12**
+
+```tsx
+<ExternalHyperlink href="https://workday.com">External Hyperlink</ExternalHyperlink>
+```
+
+**After in v13**
+
+```tsx
+<ExternalHyperlink href="https://workday.com" iconLabel="Navigate to Workday">
+  External Hyperlink
+</ExternalHyperlink>
+```
+
+### Form Field and Form Field Group 🚨
+
+**PR:** [#3254](https://github.com/Workday/canvas-kit/pull/3254)
+
+The `orientation` prop on the `FormField` component no longer accepts the deprecrated `horizontal`
+value. You must update your code to use `horizontalStart`. Our v12 release included a codemod to
+update `horizontal` to `horizontalStart`, but we kept the prop backwards-compatible. In v13, we
+dropped `horizontal` as a value, and it now requires an update.
+
+**Before in v12**
+
+```tsx
+<FormField orientation="horizontal">
+	<FormField.Label>Label</FormField.Label>
+	<FormField.Field>
+		<FormField.Input as={TextInput} />
+	<FormField.Field>
+</FormField>
+```
+
+**After in v13**
+
+```tsx
+<FormField orientation="horizontalStart">
+	<FormField.Label>Label</FormField.Label>
+	<FormField.Field>
+		<FormField.Input as={TextInput} />
+	<FormField.Field>
+</FormField>
+```
+
+### Pill (Preview) 🚨
+
+**PR:** [#3104](https://github.com/Workday/canvas-kit/pull/3104)
+
+A few changes have been made to `Pill` to ensure proper accessibility and styling.
+
+- The border color on hover has been updated from `licorice400` to
+  `system.color.border.input.strong` (`licorice500`) to match our design specs.
+- We've removed extra elements and now use
+  [flex box](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox)
+  to ensure only the label receives text overflow styles when needed.
+- Setting `maxWidth` on the parent `Pill` component now styles the child elements correctly. Before
+  v13, `maxWidth` wasn't calculating the width of all its elements and wasn't a true pixel value.
+
+#### Breaking Changes
+
+- `maxWidth` has been removed from the `usePillModel`. This config was used to style subcomponents.
+  With the refactor to use `data-part` and
+  [stencils](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--docs#create-stencil),
+  it is no longer needed on the model. You can still apply `maxWidth` on the parent `Pill` component
+  and the child elements will be styled accordingly.
+- `Pill.Icon`'s no longer has a default value of `"add"` for the `aria-label`. You _must_ provide an
+  `aria-label` for `Pill.Icon` to ensure proper accessibility. Our examples have been updated to
+  reflect this change.
+- `Pill.IconButton` no longer has a default `aria-label="remove"`. You _must_ provide an
+  `aria-label` for `Pill.IconButton` to ensure proper accessibility. Our examples have been updated
+  to reflect this change.
+- `Pill.Label` is a _required_ element when using other subcomponents such as `Pill.Icon` to ensure
+  that the label truncates correctly.
+
+**Before in v12**
+
+```tsx
+import {Pill, usePillModel} from '@workday/canvas-kit-preview-react/pill';
+
+const model = usePillModel({
+  maxWidth: 200,
+});
+
+<Pill model={model}>
+  <Pill.Icon />
+  Shoes
+</Pill>;
+```
+
+**After in v13**
+
+```tsx
+import {Pill} from '@workday/canvas-kit-preview-react/pill';
+
+<Pill maxWidth={200}>
+  <Pill.Icon aria-label='Add Shoes' />
+  <Pill.Label>Shoes</Pill.Label>
+</Pill>
+
+<Pill maxWidth={200}>
+  <Pill.Label>Shirts</Pill.Label>
+  <Pill.IconButton aria-label='Remove Shirts' />
+</Pill>
+```
+
+> 🤖 The codemod will handle the change adding `Pill.Label` if `Pill.Icon` or `Pill.IconButton` is
+> being used.
+
+### Side Panel (Preview) 🚨
+
+**PR:** [#3258](https://github.com/Workday/canvas-kit/pull/3258)
+
+When we supported IE 11 we needed to use  [CSS Animation](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations) to support animation events. Since we dropped support for IE11, we can now use [CSS Transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) to animate the `width` of the `SidePanel` when it's expanding or collapsing.
+As part of this change, we also removed the `onAnimationStart` prop. Since moving to transitions, React doesn't support `onTransitionStart`, therefore the prop is no longer needed.
+
+### Tabs 💅
+
+**PR:** [#3119](https://github.com/Workday/canvas-kit/pull/3119)
+
+- The `disabled` icon color has been updated to use `system.color.fg.disabled`. This darker icon
+  color provides better contrast.
+
+> **Note:** There should be no developer impact, and the visual changes are safe to accept.
+
+## Brand Refresh ⚡️
+
+We've also updated our logos to align with Workday's brand refresh.
+
+### Logo Updates
+
+We've removed the outdated Dub logos in Main and promoted the new logos that were previously in our
+Preview package to Main as part of the brand refresh.
+
+| Old Logo Name   | New Logo Name      |
+| --------------- | ------------------ |
+| `dubLogoBlue`   | `dubLogoPrimary`   |
+| `dubLogoWhite`  | `dubLogoReversed`  |
+| `wdayLogoBlue`  | `wdayLogoPrimary`  |
+| `wdayLogoWhite` | `wdayLogoReversed` |
+
+**Before in v12**
+
+```tsx
+// Importing from Main common
+import {dubLogoBlue} from "@workday/canvas-kit-react/common"
+
+<div dangerouslySetInnerHTML={__html: dubLogoBlue} />
+
+// Importing from Preview common
+import {dubLogoPrimary} from "@workday/canvas-kit-preview-react/common"
+
+<div dangerouslySetInnerHTML={__html: dubLogoPrimary} />
+```
+
+**After in v13**
+
+```tsx
+// New logos have been promoted to Main common AND renamed
+import {dubLogoPrimary} from "@workday/canvas-kit-preview-react/common"
+
+<div dangerouslySetInnerHTML={__html: dubLogoPrimary} />
+```
+
+> 🤖 The codemod will handle the renaming all the imports and updating the import path.
+
+## Infrastructure
+
+We've also made some updates to our dependencies and infrastructure.
+
+### Supporting `react-jsx` 🚨
+
+We've updated the `jsx` flag in our `tsconfig` to `react-jsx`. As part of this change, we've also
+updated our peer dependencies for our packages to a minimum version of `react@17.0.0`. This change
+is to provide support for modern technologies like `vite` and ES modules.
+
+#### Breaking Changes
+
+If you're using `react@16.x.x`, you'll need to upgrade to `react@17.x.x` to use Canvas Kit v13.
+
+**Note:** Because of this update, you may have issues with how your code is transpiles. In that
+case, you will likely also need to update the way `jsx` transpiles. To do this you'll need to set
+the `runtime` config to `automatic` in your Babel config presets. This feature is enabled through
+the `@babel/preset-react` preset and handles importing functions which JSX transpiles. Make sure you
+have this dev dependency installed before proceeding: `yarn add -D @babel/preset-react`. For more
+information on setting an automatic runtime for React, please
+[review Babel's documentation](https://babeljs.io/docs/babel-preset-react#react-automatic-runtime).
+
+Here's an example Babel config. Your configuration may vary based on your application setup.
+
+```json
+// babel.config.json
+{
+  "presets": [
+    [
+      "@babel/preset-react",
+      {
+        "runtime": "automatic"
+      }
+    ]
+  ]
+}
+```
+
+## Troubleshooting
+
+- 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": "^12.5.6"` -> `"@workday/canvas-kit-react": "^13.0.0"`
+  - `"@workday/canvas-kit-styling": "^12.5.6"` -> `"@workday/canvas-kit-styling": "^13.0.0"`
+  - `"@workday/canvas-kit-preview-react": "^12.5.6"` ->
+    `"@workday/canvas-kit-preview-react": "^13.0.0"`
+  - `"@workday/canvas-kit-labs-react": "^12.5.6"` -> `"@workday/canvas-kit-labs-react": "^13.0.0"`
+- 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).
+
+## Contributors
+
+This release was made possible by the following contributors:
+- [@williamjstanton](https://github.com/williamjstanton)
+- [@NehaAhujaa](https://github.com/NehaAhujaa)
+- [@JaredMaione](https://github.com/JaredMaione)
+- [@thunguyen19](https://github.com/thunguyen19)
+
+## Glossary
+
+Below is a glossary of common terms we use in this upgrade guide.
+
+### Main
+
+Our Main package of Canvas Kit (`@workday/canvas-kit-react`) provides components and utilities that
+have undergone a full design and a11y review and is approved for use in product.
+
+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.
+
+---
+
+### Preview
+
+Our Preview package of Canvas Kit (`@workday/canvas-kit-preview-react`) provides components and
+utilities that have undergone a full design and a11y review and are approved for use in product. But
+it 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 we will communicate those changes in advance and provide
+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 which is currently 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 (`@workday/canvas-kit-labs-react`) provides components and utilities
+that have **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).
+
+---
+
+## Codemod Reference
+
+# What is a Codemod?
+
+A codemod is a script that makes programmatic transformations on your codebase by traversing the
+[AST](https://www.codeshiftcommunity.com/docs/understanding-asts), identifying patterns, and making
+prescribed changes. This greatly decreases opportunities for error and reduces the number of manual
+updates, which allows you to focus on changes that need your attention. **We highly recommend you
+use the codemod for these reasons.**
+
+If you're new to running codemods or if it's been a minute since you've used one, there are a few
+things you'll want to keep in mind.
+
+- Our codemods are meant to be run sequentially. For example, if you're using v8 of Canvas Kit,
+  you'll need to run the v9 codemod before you run v10 and so on.
+- The codemod will update your code to be compatible with the specified version, but it will **not**
+  remove outdated dependencies or upgrade dependencies to the latest version. You'll need to upgrade
+  dependencies on your own.
+  - We recommend upgrading dependencies before running the codemod.
+  - Always review your `package.json` files to make sure your dependency versions look correct.
+- The codemod will not handle every breaking change in v13. You will likely need to make some manual
+  changes to be compatible. Use our Upgrade Guide as a checklist.
+- Codemods are not bulletproof.
+  - Conduct a thorough PR and QA review of all changes to ensure no regressions were introduced.
+  - As a safety precaution, we recommend committing the changes from the codemod as a single
+    isolated commit (separate from other changes) so you can roll back more easily if necessary.
+
+We're here to help! Automatic changes to your codebase can feel scary. You can always reach out to
+our team. We'd be very happy to walk you through the process to set you up for success.
+
+## Running a Codemod
+
+### Instructions
+
+The easiest way to run our codemod is to use `npx` in your terminal.```sh
+npx @workday/canvas-kit-codemod v${canvasKitMajorVersionNumber} [path]
+```
+
+Be sure to provide specific directories that need to be updated via the `[path]` argument. This
+decreases the amount of AST the codemod needs to traverse and reduces the chances of the script
+having an error. For example, if your source code lives in `src/`, use `src/` as your `[path]`. Or,
+if you have a monorepo with three packages using Canvas Kit, provide those specific packages as your
+`[path]`.
+
+Alternatively, if you're unable to run the codemod successfully using `npx`, you can install the
+codemod package as a dev dependency, run it with `yarn`, and then remove the package after you're
+finished.
+
+```sh
+yarn add @workday/canvas-kit-codemod --dev
+yarn canvas-kit-codemod v${canvasKitMajorVersion} [path]
+yarn remove @workday/canvas-kit-codemod
+```
+
+> **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
+> manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
+> after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
+> your project conventions.
+
+## Codemod Transformations for v13
+
+The following automated transformations are available for upgrading to v13:
+
+- **Add Pill Label**: addPillLabel
+- **Promote Expandable**: promoteExpandable
+- **Rename Dub Logos Imports**: renameDubLogosImports
+- **Rename Dub Logos References**: renameDubLogosReferences
+
+Run the codemod with: `npx @workday/canvas-kit-codemod v13 [path]`

package/dist/types/lib/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function main(): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/types/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../lib/cli.ts"],"names":[],"mappings":";AAKA,wBAAsB,IAAI,kBAGzB"}

package/dist/types/lib/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function getServer(): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAKlE,wBAAgB,SAAS,cA6HxB"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@workday/canvas-kit-mcp",
+  "version": "13.2.41",
+  "description": "MCP package for Canvas Kit",
+  "author": "Workday, Inc. (https://www.workday.com)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/workday/canvas-kit.git",
+    "directory": "modules/mcp"
+  },
+  "bin": {
+    "canvas-kit-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./lib": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build:copy": "tsx ./build/index.ts",
+    "build:types": "tsc --project tsconfig.build.json -d true --declarationDir dist/types --emitDeclarationOnly --pretty",
+    "build:mcp": "esbuild lib/index.ts --bundle --platform=node --outfile=dist/index.js --format=esm --sourcemap && esbuild lib/cli.ts --bundle --platform=node --outfile=dist/cli.js --format=esm --sourcemap",
+    "build": "npm-run-all build:copy build:types build:mcp",
+    "clean": "rimraf dist && rimraf .build-info && mkdirp dist"
+  },
+  "keywords": [
+    "canvas",
+    "canvas-kit",
+    "workday",
+    "mcp"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2"
+  },
+  "devDependencies": {
+    "@types/node": "^14.0.0",
+    "esbuild": "^0.25.11",
+    "mkdirp": "^1.0.3",
+    "rimraf": "^5.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "5.0"
+  },
+  "gitHead": "45cc5255aa2e83d7f1257ebca7b87ee0abb96689"
+}