@kaizen/components 1.74.3 → 1.75.1

package/dist/types/GuidanceBlock/GuidanceBlock.d.ts

@@ -1,10 +1,10 @@
 import React from 'react';
-import { type ButtonProps } from "../Button";
+import { type ButtonProps as V1ButtonProps } from "../Button";
 import { type HeadingProps } from "../Heading";
 import { type SceneProps, type SpotProps } from "../Illustration";
 import { type TooltipProps } from "../Tooltip";
 import { type VariantType } from './types';
-export type ActionProps = ButtonProps & {
+export type ActionProps = V1ButtonProps & {
     'tooltip'?: TooltipProps;
     'aria-label'?: string;
     'aria-labelledby'?: string;
@@ -25,9 +25,14 @@ type BaseGuidanceBlockProps = {
     illustration: React.ReactElement<SpotProps | SceneProps>;
     illustrationType?: IllustrationType;
     smallScreenTextAlignment?: TextAlignment;
+    /** @deprecated use the `actionsSlot` prop with Button/next instead */
     actions?: GuidanceBlockActions;
+    /** A slot for the primary and secondary action. It is recommended to use the {@link https://cultureamp.design/?path=/docs/components-button-button-next-api-specification--docs | Button} or {@link https://cultureamp.design/?path=/docs/components-linkbutton-usage-guidelines--docs | LinkButton} wrapped in fragment. */
+    actionsSlot?: React.ReactNode;
+    /** @deprecated this is no longer a used feature and is only the deprecated `actions` prop, ie: {secondary: { label: "Dismiss action" }}` */
     secondaryDismiss?: boolean;
     variant?: VariantType;
+    /**  @deprecated use the `actionsSlot` and pass the icon into the JSX elements */
     withActionButtonArrow?: boolean;
     noMaxWidth?: boolean;
 };
@@ -45,14 +50,13 @@ export type GuidanceBlockProps = GuidanceBlockWithText | GuidanceBlockPropsWithC
 export type GuidanceBlockState = {
     hidden: boolean;
     removed: boolean;
-    mediaQueryLayout: string;
 };
 /**
  * {@link https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3082093807/Guidance+Block Guidance} |
  * {@link https://cultureamp.design/?path=/docs/components-guidanceblock--docs Storybook}
  */
 export declare const GuidanceBlock: {
-    ({ layout, variant, withActionButtonArrow, noMaxWidth, illustrationType, smallScreenTextAlignment, actions, illustration, secondaryDismiss, ...restProps }: GuidanceBlockProps): JSX.Element;
+    ({ layout, variant, withActionButtonArrow, noMaxWidth, illustrationType, smallScreenTextAlignment, actions, illustration, secondaryDismiss, actionsSlot, ...restProps }: GuidanceBlockProps): JSX.Element;
     displayName: string;
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.74.3",
+  "version": "1.75.1",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -143,7 +143,6 @@
     "react-day-picker": "8.10.1",
     "react-focus-lock": "^2.13.6",
     "react-focus-on": "^3.9.4",
-    "react-media": "^1.10.0",
     "react-popper": "^2.3.0",
     "react-select": "^5.10.1",
     "react-textfit": "^1.1.1",
@@ -179,14 +178,14 @@
     "react-dom": "^18.3.1",
     "react-highlight": "^0.15.0",
     "react-intl": "^7.1.10",
-    "rollup": "^4.38.0",
+    "rollup": "^4.39.0",
     "sass": "1.79.6",
     "serialize-query-params": "^2.0.2",
     "svgo": "^3.3.2",
     "tslib": "^2.8.1",
     "tsx": "^4.19.3",
-    "@kaizen/design-tokens": "10.8.9",
-    "@kaizen/package-bundler": "2.0.6"
+    "@kaizen/design-tokens": "10.8.10",
+    "@kaizen/package-bundler": "2.0.7"
   },
   "devDependenciesComments": {
     "sass": "Prevent deprecation warnings introduced in 1.80 as we plan to move away from sass",

package/src/GuidanceBlock/GuidanceBlock.module.css

@@ -1,11 +1,3 @@
-.rightMargin {
-  margin-right: var(--spacing-8);
-}
-
-.noRightMargin {
-  margin-right: 0;
-}
-
 .banner.noMaxWidth {
   max-width: inherit;
 }
@@ -121,7 +113,6 @@
 
 .buttonContainer {
   display: flex;
-  flex: 1 0 auto;
   justify-content: center;
   flex-direction: row-reverse;
   gap: var(--spacing-12);

package/src/GuidanceBlock/GuidanceBlock.tsx

@@ -1,16 +1,16 @@
-import React, { useEffect, useState } from 'react'
+import React, { useState } from 'react'
 import classNames from 'classnames'
-import Media from 'react-media'
-import { Button, type ButtonProps } from '~components/Button'
+import { Button as V1Button, type ButtonProps as V1ButtonProps } from '~components/Button'
 import { Heading, type HeadingProps } from '~components/Heading'
 import { type SceneProps, type SpotProps } from '~components/Illustration'
 import { Text } from '~components/Text'
 import { Tooltip, type TooltipProps } from '~components/Tooltip'
-import { Icon } from '~components/__next__/Icon'
+import { Icon } from '~components/__next__'
+import { useMediaQueries } from '~components/utils/useMediaQueries'
 import { type VariantType } from './types'
 import styles from './GuidanceBlock.module.css'
 
-export type ActionProps = ButtonProps & {
+export type ActionProps = V1ButtonProps & {
   'tooltip'?: TooltipProps
   'aria-label'?: string
   'aria-labelledby'?: string
@@ -38,14 +38,15 @@ type BaseGuidanceBlockProps = {
    * Sets how the width and aspect ratio will respond to the Illustration passed in.
    */
   illustrationType?: IllustrationType
-
   smallScreenTextAlignment?: TextAlignment
+  /** @deprecated use the `actionsSlot` prop with Button/next instead */
   actions?: GuidanceBlockActions
-  /*
-   * This will still require the secondary object to be passed into the actions ie: {secondary: { label: "Dismiss action" }}`
-   */
+  /** A slot for the primary and secondary action. It is recommended to use the {@link https://cultureamp.design/?path=/docs/components-button-button-next-api-specification--docs | Button} or {@link https://cultureamp.design/?path=/docs/components-linkbutton-usage-guidelines--docs | LinkButton} wrapped in fragment. */
+  actionsSlot?: React.ReactNode
+  /** @deprecated this is no longer a used feature and is only the deprecated `actions` prop, ie: {secondary: { label: "Dismiss action" }}` */
   secondaryDismiss?: boolean
   variant?: VariantType
+  /**  @deprecated use the `actionsSlot` and pass the icon into the JSX elements */
   withActionButtonArrow?: boolean
   noMaxWidth?: boolean
 }
@@ -67,7 +68,6 @@ export type GuidanceBlockProps = GuidanceBlockWithText | GuidanceBlockPropsWithC
 export type GuidanceBlockState = {
   hidden: boolean
   removed: boolean
-  mediaQueryLayout: string
 }
 
 type WithTooltipProps = {
@@ -92,22 +92,15 @@ export const GuidanceBlock = ({
   actions,
   illustration,
   secondaryDismiss,
+  actionsSlot,
   ...restProps
 }: GuidanceBlockProps): JSX.Element => {
   const [hidden, setHidden] = useState<boolean>(false)
   const [removed, setRemoved] = useState<boolean>(false)
-  const [mediaQueryLayout, setMediaQueryLayout] = useState<string>('')
+  const { queries } = useMediaQueries()
 
   const containerRef = React.createRef<HTMLDivElement>()
 
-  useEffect(() => {
-    if (layout === 'inline' || layout === 'stacked') {
-      containerQuery()
-    }
-    // @todo: Fix if possible - avoiding breaking in eslint upgrade
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
-
   const handleDismissBanner = (): void => {
     setHidden(true)
     actions?.dismiss?.onClick()
@@ -120,24 +113,6 @@ export const GuidanceBlock = ({
     }
   }
 
-  const containerQuery = (): void => {
-    const resizeObserver = new ResizeObserver((entries) => {
-      if (entries.length === 1) {
-        handleMediaQueryLayout(entries[0].contentRect.width)
-      }
-    })
-
-    resizeObserver.observe(containerRef.current as HTMLElement)
-  }
-
-  const handleMediaQueryLayout = (width: number): void => {
-    if (width <= 320) {
-      setMediaQueryLayout('centerContent')
-    } else {
-      setMediaQueryLayout('')
-    }
-  }
-
   const marginTop = (): string => {
     if (hidden && containerRef.current) {
       return -containerRef.current.clientHeight + 'px'
@@ -150,8 +125,6 @@ export const GuidanceBlock = ({
     return <></>
   }
 
-  const componentIsMobile = mediaQueryLayout.includes('centerContent')
-
   return (
     <div
       className={classNames(
@@ -159,7 +132,7 @@ export const GuidanceBlock = ({
         variant && styles[variant],
         layout && styles[layout],
         hidden && styles.hidden,
-        mediaQueryLayout === 'centerContent' && styles.centerContent,
+        queries.isSmall && styles.centerContent,
         noMaxWidth && styles.noMaxWidth,
         illustrationType === 'scene' && styles.hasSceneIllustration,
         smallScreenTextAlignment === 'left' && styles.smallScreenTextAlignment,
@@ -193,55 +166,43 @@ export const GuidanceBlock = ({
             </>
           )}
         </div>
-        {actions?.primary && (
-          <Media query="(max-width: 767px)">
-            {(isMobile: boolean): JSX.Element => (
-              <div
-                className={classNames({
-                  noRightMargin: isMobile || componentIsMobile,
-                  rightMargin: !(isMobile || componentIsMobile) && layout === 'default',
-                })}
-              >
-                <div
-                  className={classNames(
-                    styles.buttonContainer,
-                    actions?.secondary && styles.secondaryAction,
-                  )}
-                >
-                  <WithTooltip tooltipProps={actions.primary.tooltip}>
-                    <Button
-                      icon={
-                        withActionButtonArrow ? (
-                          <Icon name="arrow_forward" isPresentational shouldMirrorInRTL />
-                        ) : undefined
-                      }
-                      iconPosition="end"
-                      {...actions.primary}
-                      fullWidth={isMobile || componentIsMobile}
-                    />
+        {actions?.primary || actionsSlot ? (
+          <div className={styles.buttonContainer}>
+            {actions?.primary && (
+              <>
+                <WithTooltip tooltipProps={actions.primary.tooltip}>
+                  <V1Button
+                    icon={
+                      withActionButtonArrow ? (
+                        <Icon name="arrow_forward" isPresentational shouldMirrorInRTL />
+                      ) : undefined
+                    }
+                    iconPosition="end"
+                    {...actions.primary}
+                    fullWidth={queries.isSmall}
+                  />
+                </WithTooltip>
+                {actions?.secondary && (
+                  <WithTooltip tooltipProps={actions.secondary.tooltip}>
+                    <div className={styles.secondaryAction}>
+                      <V1Button
+                        secondary
+                        {...actions.secondary}
+                        onClick={
+                          secondaryDismiss
+                            ? (): void => handleDismissBanner()
+                            : actions?.secondary?.onClick
+                        }
+                        fullWidth={queries.isSmall}
+                      />
+                    </div>
                   </WithTooltip>
-
-                  {actions?.secondary && (
-                    <WithTooltip tooltipProps={actions.secondary.tooltip}>
-                      <div className={styles.secondaryAction}>
-                        <Button
-                          secondary
-                          {...actions.secondary}
-                          onClick={
-                            secondaryDismiss
-                              ? (): void => handleDismissBanner()
-                              : actions?.secondary?.onClick
-                          }
-                          fullWidth={isMobile || componentIsMobile}
-                        />
-                      </div>
-                    </WithTooltip>
-                  )}
-                </div>
-              </div>
+                )}
+              </>
             )}
-          </Media>
-        )}
+            {!actions && actionsSlot && actionsSlot}
+          </div>
+        ) : null}
       </div>
     </div>
   )

package/src/GuidanceBlock/_docs/GuidanceBlock--migration-guide.mdx

@@ -0,0 +1,77 @@
+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-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` 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.

package/src/GuidanceBlock/_docs/GuidanceBlock.mdx

@@ -25,14 +25,43 @@ It guides people to new actions they haven't done before or connects them to rel
 
 ## API
 
-<DocsStory of={GuidanceBlockStories.Actions} />
+### actionsSlot
 
-<DocsStory of={GuidanceBlockStories.Tooltip} />
+The `actionsSlot` slot is used to render the GuidanceBlock's primary and secondary action. This supersedes the deprecated `actions` prop and should be used with [LinkButton](https://cultureamp.design/?path=/docs/components-linkbutton-api-specification--docs) or [Button](https://cultureamp.design/?path=/docs/components-button-button-next-api-specification--docs) component.
 
-<DocsStory of={GuidanceBlockStories.CustomContent} />
+<Canvas of={GuidanceBlockStories.ActionsSlot} />
 
-<DocsStory of={GuidanceBlockStories.Stacked} />
+It is recommended that the primary and secondary actions use their respective variants (`secondary` and `tertiary`) within the Button component to ensure continuity in designs.
 
-<DocsStory of={GuidanceBlockStories.SceneExample} />
+#### actionsSlot with tooltip
 
-<DocsStory of={GuidanceBlockStories.Variants} />
+The new actionsSlot allows use to use the modern Tooltip. Refer to the [docs here](https://cultureamp.design/?path=/docs/components-tooltip-tooltip-next-api-specification--docs) for more tooltip configuration options.
+
+<Canvas of={GuidanceBlockStories.ActionsSlotWithTooltips} />
+
+### actions (deprecated)
+
+The actions prop is deprecated. Use the [actionsSlot](#actionsslot) slot instead with the `LinkButton` or `Button` component instead.
+
+<Canvas of={GuidanceBlockStories.Actions} />
+
+#### actions (deprecated) with tooltip
+
+<Canvas of={GuidanceBlockStories.Tooltip} />
+
+### Custom content
+
+<Canvas of={GuidanceBlockStories.CustomContent} />
+
+### Stacked
+
+<Canvas of={GuidanceBlockStories.Stacked} />
+
+### Scene Illustrations
+
+<Canvas of={GuidanceBlockStories.SceneExample} />
+
+### Variants
+
+<Canvas of={GuidanceBlockStories.Variants} />
+```

package/src/GuidanceBlock/_docs/GuidanceBlock.stickersheet.stories.tsx

@@ -2,8 +2,15 @@ import React from 'react'
 import { type Meta } from '@storybook/react'
 import { Heading } from '~components/Heading'
 import { EmptyStatesPositive, Informative } from '~components/Illustration'
+import { LinkButton } from '~components/LinkButton'
 import { Tag } from '~components/Tag'
 import { Text } from '~components/Text'
+import { Icon } from '~components/__next__'
+import { Button } from '~components/__next__/Button'
+import {
+  Tooltip as TooltipNext,
+  TooltipTrigger as TooltipTriggerNext,
+} from '~components/__next__/Tooltip'
 import { StickerSheet, type StickerSheetStory } from '~storybook/components/StickerSheet'
 import { GuidanceBlock, type GuidanceBlockProps } from '../index'
 import { variantsMap } from '../types'
@@ -17,23 +24,24 @@ export default {
 } satisfies Meta
 
 const GENERIC_PROPS = {
-  persistent: true,
   illustration: <Informative alt="" />,
-  actions: {
-    primary: {
-      label: 'Action',
-      onClick: () => {
-        alert('tada: 🎉')
-      },
-    },
-    secondary: {
-      label: 'Pass',
-      onClick: () => {
-        alert('tada: 🎉')
-      },
-    },
-  },
-}
+  actionsSlot: (
+    <>
+      <Button
+        variant="secondary"
+        onPress={() => alert('tada: 🎉')}
+        size="large"
+        iconPosition="end"
+        icon={<Icon name={'arrow_forward'} shouldMirrorInRTL isPresentational />}
+      >
+        Action
+      </Button>
+      <LinkButton variant="tertiary" href="#lorem" onPress={() => alert('tracking')} size="large">
+        Pass
+      </LinkButton>
+    </>
+  ),
+} satisfies Partial<GuidanceBlockProps>
 
 const TEXT_PROPS: GuidanceBlockProps = {
   ...GENERIC_PROPS,
@@ -67,7 +75,24 @@ const StickerSheetTemplate: StickerSheetStory = {
         ))}
       </>
       <StickerSheet.Row header="No arrow">
-        <GuidanceBlock withActionButtonArrow={false} {...TEXT_PROPS} />
+        <GuidanceBlock
+          {...TEXT_PROPS}
+          actionsSlot={
+            <>
+              <Button variant="secondary" onPress={() => alert('tada: 🎉')} size="large">
+                Action
+              </Button>
+              <LinkButton
+                variant="tertiary"
+                href="#lorem"
+                onPress={() => alert('tracking')}
+                size="large"
+              >
+                Pass
+              </LinkButton>
+            </>
+          }
+        />
       </StickerSheet.Row>
       <StickerSheet.Row header="Custom Content">
         <GuidanceBlock {...CONTENT_PROPS} />
@@ -75,16 +100,24 @@ const StickerSheetTemplate: StickerSheetStory = {
       <StickerSheet.Row header="Tooltip">
         <GuidanceBlock
           {...TEXT_PROPS}
-          actions={{
-            primary: {
-              ...GENERIC_PROPS.actions.primary,
-              tooltip: {
-                text: 'Opens in a new tab',
-                mood: 'cautionary',
-                isInitiallyVisible: true,
-              },
-            },
-          }}
+          actionsSlot={
+            <>
+              <TooltipTriggerNext defaultOpen>
+                <LinkButton
+                  variant="secondary"
+                  href="#lorem"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  size="large"
+                  iconPosition="end"
+                  icon={<Icon name="arrow_forward" shouldMirrorInRTL isPresentational />}
+                >
+                  Learn more
+                </LinkButton>
+                <TooltipNext>Opens in a new tab</TooltipNext>
+              </TooltipTriggerNext>
+            </>
+          }
         />
       </StickerSheet.Row>
       <StickerSheet.Row header="Scene Illustration">