From be64cfa2078024286d609d7ada7ee64e4be00453 Mon Sep 17 00:00:00 2001 From: Michael Winter Date: Wed, 12 Feb 2025 10:18:47 +1100 Subject: [PATCH] add button migration guide and update outputs for codemod --- packages/components/bin/codemod.sh | 2 + .../codemods/upgradeV1Buttons/index.ts | 2 + .../Button/_docs/Button--migration-guide.mdx | 58 +++++++++++++++++++ 3 files changed, 62 insertions(+) create mode 100644 packages/components/src/__rc__/Button/_docs/Button--migration-guide.mdx diff --git a/packages/components/bin/codemod.sh b/packages/components/bin/codemod.sh index 07c43c4bbac..070a86bf0aa 100755 --- a/packages/components/bin/codemod.sh +++ b/packages/components/bin/codemod.sh @@ -31,6 +31,8 @@ echo "" if npx tsx@latest $CODEMOD_PATH $TARGET_DIR; then echo "Codemod '$codemodFileName' completed successfully in directory '$transformDir'" + echo "---" + echo "Run linting and prettier to correct issues with re-writes" else echo "Codemod '$codemodFileName' could not be run in '$TARGET_DIR'" exit 1 diff --git a/packages/components/codemods/upgradeV1Buttons/index.ts b/packages/components/codemods/upgradeV1Buttons/index.ts index 32e3375c3e0..ef1fe9b7e40 100644 --- a/packages/components/codemods/upgradeV1Buttons/index.ts +++ b/packages/components/codemods/upgradeV1Buttons/index.ts @@ -2,6 +2,8 @@ import { transformComponentsInDir } from '../utils' import { upgradeV1Buttons } from './upgradeV1Buttons' const run = (): void => { + console.log('It is recommended that the `upgradeIconV1` codemod be run prior to this') + console.log('---') console.log('~(-_- ~) Running V1 Buttons upgrade (~ -_-)~') const targetDir = process.argv[2] diff --git a/packages/components/src/__rc__/Button/_docs/Button--migration-guide.mdx b/packages/components/src/__rc__/Button/_docs/Button--migration-guide.mdx new file mode 100644 index 00000000000..4a526747ba0 --- /dev/null +++ b/packages/components/src/__rc__/Button/_docs/Button--migration-guide.mdx @@ -0,0 +1,58 @@ +import { Canvas, Meta, Controls, Story } from '@storybook/blocks' +import { ResourceLinks, KAIOInstallation } from '~storybook/components' + + + +# Button Migration Guide + +This is a short guide to assist in migration from the old to new `Button` and `LinkButton` component. + +## Key API differences + +Below is a list of notable changes when migrating to the new `Button` and `LinkButton` component: + +- `label` is now handled as `Children` and does not have a specific prop. +- Variants, such as `primary` and `secondary`, are now controlled as by the single `variant` prop. +- `onClick` and other event handlers now reflect the RAC event ecosystems, ie: `onPress`. + - You can see more about the RAC event ecosystem [here](https://react-spectrum.adobe.com/react-aria/Button.html#events). +- `Button` and `LinkButton` now exist as separate components. + - The intent is to more closely align to the semantic roles of an anchor or button and should be used accordingly. +- `LinkButton` handles native navigation via `href` out of the box but additional config can be used to allow for client side routing - [see here](/docs/components-linkbutton-api-specification--docs#client-side-routing). + - `onPress` can still be used in place of `onClick` for pushing to routers. +- `IconButton` has been superseded by icon props and the [icon-only pattern](/docs/components-button-button-v3-api-specification--docs#icon-only-button-and-hashiddenlabel). +- `working` props has been updated to `pending` to better reflect the state of the button. +- `badge` prop has been removed and should be handled within the `Children` where required. +- `size` props have been adjusted to include `small`, `medium` and `large`. +- Styles have been consolidate to align with modern designs and variants like `destructive` have been removed. + - The codemod will remap these to the relative variants. +- Reversed styles should be handled by the `ReversedColors` Provider but for ease of migration can use the `isReversed` prop. + +## Codemod + +To assist in migration we have created the `upgradeV1Buttons` codemod. + +This will loop through the given directory and update all instances of Button to the latest implementation. You can refer to this [README](https://github.com/cultureamp/kaizen-design-system/blob/main/packages/components/codemods/README.md#kaizen-codemods) on how to run kaizen codemods using the CLI within your repository, ie: + +```bash +pnpm kaizen-codemod src upgradeV1Buttons +``` + +### Pre-requisites + +It is also recommended that the `upgradeIconV1` codemod is run before `upgradeV1Buttons` to ensure that all icons are updated to the new `Icon` component that uses the Material icons CDN. Seem more about this [here](/docs/components-icon-icon-future-api-specification--docs#set-up). + +### Potential gotchas + +If you're facing any issues not captured below, reach out to the [#help_design_system](https://cultureamp.slack.com/archives/C0189KBPM4Y) channel on Slack. + +### `icon` props and sizing + +While the `icon` prop supports any `JSX` element, only the latest [Icon component](/docs/components-icon-icon-future-api-specification--docs) will be able to handle relative sizing and spacing automatically within the Button. We recommend running the `upgradeIconV1` codemod before this to convert all icons to the latest implementation. See the guidance here on using the [Material Icons CDN](/docs/guides-app-starter--docs#5-link-to-google-material-symbols-cdn). + +### `component` render props and intentional type errors + +Based off Metabase queries, `component` render props is used in consuming repositories to wrap Button content with a routing solution, such as NextJS's `Link` component. To ensure a safe migration, the codemod will update any usages to a `LinkButton` with the `component` prop still passed in. This will cause an intentional type error to provide feedback and make it easier to find in the codebase for a manual update. This should be able to be converted to use client side routing by following the [LinkButton API docs](https://cultureamp.design/?path=/docs/components-linkbutton-api-specification--docs). + +## More information + +For more information on the about each of the new API's, we recommend referring the [Button](/docs/components-button-button-v3-api-specification--docs) or [LinkButton](/docs/components-linkbutton-api-specification--docs) API specifications.