import { Canvas, Meta, Controls, Story } from '@storybook/blocks'
import { ResourceLinks, KAIOInstallation } from '~storybook/components'

<Meta title="Components/GuidanceBlock/Migration Guide" />

# GuidanceBlock `actions` Migration Guide

This is a short guide to assist in migration from the `actions` to `actionsSlot` prop.

## Key API differences

Below is a list of notable changes when migrating:

- `actionsSlot` added
  - This accepts a JSX element to render the primary and secondary actions
- `actions` prop is deprecated
  - This uses the V1 `Button` component which is being dropped in the next cycle
- `secondaryDismiss` prop is deprecated
  - A dismissible GuidanceBlock is no longer used across the platform
- `withActionButtonArrow` prop is deprecated
  - Icons should be handled within the `Button` or `LinkButton` component

### Mapping primary and secondary actions to the correct Button variant

The primary action is mapped to the `secondary` variant and secondary action is mapped to the `tertiary` variant, i.e:

```tsx
<Button variant="secondary" size="large" {...otherButtonProps}>Primary Action</Button>
<Button variant="tertiary" size="large" {...otherButtonProps}>Secondary Action</Button>
```

Note that within GuidanceBlock the size of the buttons is `large`.

## Codemod

To assist in migration we have created the `migrateGuidanceBlockActionsToActionsSlot` codemod.

This will loop through the given directory and attempt to update all instances of GuidanceBlock to use the `actionsSlot`. 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 migrateGuidanceBlockActionsToActionsSlot
```

Note that there are cases where props that no longer exist will be left in the codebase to throw type error and provide feedback to the engineer. This is intentional and identifies area's where manual updates are required.

### Codemod 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-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` props 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).

#### `badge` props type errors

The codemod will continue to pass `badge` props into the new implementation so it will throw a type error and provide feedback to engineers. This will need to be manually composed within the `Children` if required, ie:

```
import { Badge } from "@kaizen/components"
import { Button } from "@kaizen/components/next"

<Button>Label<Badge classNameOverride="ms-8" variant="success">New</Badge></Button>
```

#### `tooltip` props type errors

Tooltips will need to be manually migrated to the latest version. Refer to the GuidanceBlock stories as an example.

#### Link related props type errors

If no `href` or `component` props are passed to the component you may get type errors for having anchor related props passed into a Button, ie: `target`, `rel`.

This will cause a type error that can be corrected by either using the `LinkButton` (if intended) or removing all anchor related props as they shouldn't exist on semantic buttons.