@kaizen/components 1.57.1 → 1.58.0

package/src/__containers__/GuidanceBlock/v2/GuidanceBlock.tsx

@@ -0,0 +1,262 @@
+import React, { useEffect, useState } from "react"
+import classNames from "classnames"
+import Media from "react-media"
+import { Heading, HeadingProps } from "~components/Heading"
+import { ArrowForwardIcon } from "~components/Icon"
+import { SceneProps, SpotProps } from "~components/Illustration"
+import { Text } from "~components/Text"
+import { Button, ButtonProps } from "~components/__actions__/v2"
+import { Tooltip, TooltipProps } from "~components/__overlays__/Tooltip/v1"
+import styles from "./GuidanceBlock.module.scss"
+
+export type ActionProps = ButtonProps & {
+  tooltip?: TooltipProps
+}
+
+type LayoutType = "default" | "inline" | "stacked"
+
+type IllustrationType = "spot" | "scene"
+
+type TextAlignment = "center" | "left"
+
+type GuidanceBlockActions = {
+  primary: ActionProps
+  secondary?: ActionProps
+  dismiss?: {
+    onClick: () => void
+  }
+}
+
+type BaseGuidanceBlockProps = {
+  layout?: LayoutType
+  illustration: React.ReactElement<SpotProps | SceneProps>
+  /*
+   * Sets how the width and aspect ratio will respond to the Illustration passed in.
+   */
+  illustrationType?: IllustrationType
+
+  smallScreenTextAlignment?: TextAlignment
+  actions?: GuidanceBlockActions
+  /*
+   * This will still require the secondary object to be passed into the actions ie: {secondary: { label: "Dismiss action" }}`
+   */
+  secondaryDismiss?: boolean
+  /**
+   * If you are migrating from the KAIO v1:
+   * - `prominent` is now `expert-advice`
+   * - All other variants are removed in favour of `default`
+   */
+  variant?: "default" | "expert-advice"
+  withActionButtonArrow?: boolean
+  noMaxWidth?: boolean
+}
+
+type GuidanceBlockWithText = {
+  text: {
+    title: string
+    titleTag?: HeadingProps["tag"]
+    description: string | React.ReactNode
+  }
+} & BaseGuidanceBlockProps
+
+type GuidanceBlockPropsWithContent = {
+  content: React.ReactElement
+} & BaseGuidanceBlockProps
+
+export type GuidanceBlockProps =
+  | GuidanceBlockWithText
+  | GuidanceBlockPropsWithContent
+
+export type GuidanceBlockState = {
+  hidden: boolean
+  removed: boolean
+  mediaQueryLayout: string
+}
+
+type WithTooltipProps = {
+  children: React.ReactNode
+  tooltipProps?: TooltipProps
+}
+
+const WithTooltip = ({
+  tooltipProps,
+  children,
+}: WithTooltipProps): JSX.Element =>
+  !!tooltipProps ? (
+    <Tooltip {...tooltipProps}>{children}</Tooltip>
+  ) : (
+    <>{children}</>
+  )
+
+/**
+ * {@link https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3082093807/Guidance+Block Guidance} |
+ * {@link https://cultureamp.design/?path=/docs/components-guidanceblock--docs Storybook}
+ */
+export const GuidanceBlock = ({
+  layout = "default",
+  variant = "default",
+  withActionButtonArrow = true,
+  noMaxWidth = false,
+  illustrationType = "spot",
+  smallScreenTextAlignment = "center",
+  actions,
+  illustration,
+  secondaryDismiss,
+  ...restProps
+}: GuidanceBlockProps): JSX.Element => {
+  const [hidden, setHidden] = useState<boolean>(false)
+  const [removed, setRemoved] = useState<boolean>(false)
+  const [mediaQueryLayout, setMediaQueryLayout] = useState<string>("")
+
+  const containerRef = React.createRef<HTMLDivElement>()
+
+  useEffect(() => {
+    if (layout === "inline" || layout === "stacked") {
+      containerQuery()
+    }
+  }, [])
+
+  const handleDismissBanner = (): void => {
+    setHidden(true)
+    actions?.dismiss?.onClick()
+  }
+
+  const onTransitionEnd = (e: React.TransitionEvent<HTMLDivElement>): void => {
+    // Be careful: this assumes the final CSS property to be animated is "margin-top".
+    if (hidden && e.propertyName === "margin-top") {
+      setRemoved(true)
+    }
+  }
+
+  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"
+    }
+
+    return "0"
+  }
+
+  if (removed) {
+    return <></>
+  }
+
+  const componentIsMobile = mediaQueryLayout.includes("centerContent")
+
+  return (
+    <div
+      className={classNames(
+        styles.banner,
+        variant && styles[variant],
+        layout && styles[layout],
+        hidden && styles.hidden,
+        mediaQueryLayout === "centerContent" && styles.centerContent,
+        noMaxWidth && styles.noMaxWidth,
+        illustrationType === "scene" && styles.hasSceneIllustration,
+        smallScreenTextAlignment === "left" && styles.smallScreenTextAlignment
+      )}
+      style={{
+        marginTop: marginTop(),
+      }}
+      ref={containerRef}
+      onTransitionEnd={onTransitionEnd}
+    >
+      <div className={styles.illustrationWrapper}>
+        <div className={styles.illustration}>
+          {illustrationType === "scene"
+            ? React.cloneElement(illustration, { enableAspectRatio: true })
+            : illustration}
+        </div>
+      </div>
+      <div className={styles.descriptionAndActions}>
+        <div className={styles.descriptionContainer}>
+          {"content" in restProps && restProps.content}
+          {"text" in restProps && (
+            <>
+              <div className={styles.headingWrapper}>
+                <Heading
+                  tag={restProps?.text?.titleTag ?? "h3"}
+                  variant="heading-3"
+                >
+                  {restProps?.text?.title}
+                </Heading>
+              </div>
+              <Text tag="p" variant="body">
+                {restProps?.text?.description}
+              </Text>
+            </>
+          )}
+        </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 ? (
+                          <ArrowForwardIcon role="presentation" />
+                        ) : undefined
+                      }
+                      iconPosition="end"
+                      {...actions.primary}
+                      fullWidth={isMobile || componentIsMobile}
+                    />
+                  </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>
+        )}
+      </div>
+    </div>
+  )
+}
+
+GuidanceBlock.displayName = "GuidanceBlock"

package/src/__containers__/GuidanceBlock/v2/_docs/GuidanceBlock.mdx

@@ -0,0 +1,38 @@
+import { Canvas, Controls, DocsStory, Meta } from "@storybook/blocks"
+import { ResourceLinks, KAIOInstallation } from "~storybook/components"
+import * as GuidanceBlockStories from "./GuidanceBlock.stories"
+
+<Meta of={GuidanceBlockStories} />
+
+# GuidanceBlock (V2)
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/GuidanceBlock"
+  figma="https://www.figma.com/file/ZRfnoNUXbGZv4eVWLbF4Az/%EF%B8%8F%F0%9F%96%BC%EF%B8%8F-Component-Gallery?node-id=622%3A149926&t=P1w10jr2cpPuaayw-1"
+  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3082093807/Guidance+Block"
+
+/>
+
+<KAIOInstallation exportNames="GuidanceBlock" version="2" family="containers" />
+
+## Overview
+
+A Guidance Block provides a familiar layout that is visually prominent to draw attention to related content.
+It guides people to new actions they haven't done before or connects them to relevant content they can view on another page.
+
+<Canvas of={GuidanceBlockStories.Playground} />
+<Controls of={GuidanceBlockStories.Playground} />
+
+## API
+
+<DocsStory of={GuidanceBlockStories.Actions} />
+
+<DocsStory of={GuidanceBlockStories.Tooltip} />
+
+<DocsStory of={GuidanceBlockStories.CustomContent} />
+
+<DocsStory of={GuidanceBlockStories.Stacked} />
+
+<DocsStory of={GuidanceBlockStories.SceneExample} />
+
+<DocsStory of={GuidanceBlockStories.Variants} />

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

@@ -0,0 +1,118 @@
+import React from "react"
+import { Meta } from "@storybook/react"
+import { Heading } from "~components/Heading"
+import { EmptyStatesPositive, Informative } from "~components/Illustration"
+import { Tag } from "~components/Tag"
+import { Text } from "~components/Text"
+import {
+  StickerSheet,
+  StickerSheetStory,
+} from "~storybook/components/StickerSheet"
+import { GuidanceBlock, GuidanceBlockProps } from "../index"
+
+export default {
+  title: "Containers/GuidanceBlock/v2",
+  parameters: {
+    chromatic: { disable: false },
+    controls: { disable: true },
+  },
+} satisfies Meta
+
+const GENERIC_PROPS = {
+  persistent: true,
+  illustration: <Informative alt="" />,
+  actions: {
+    primary: {
+      label: "Action",
+      onClick: () => {
+        alert("tada: 🎉")
+      },
+    },
+    secondary: {
+      label: "Pass",
+      onClick: () => {
+        alert("tada: 🎉")
+      },
+    },
+  },
+}
+
+const TEXT_PROPS: GuidanceBlockProps = {
+  ...GENERIC_PROPS,
+  text: {
+    title: "This is the Guidance block title",
+    description:
+      "Mussum Ipsum, cacilds vidis litro abertis. Suco de cevadiss, é um leite divinis, " +
+      "qui tem lupuliz, matis, aguis e fermentis. Mé faiz elementum girarzis, nisi eros vermeio.",
+  },
+}
+
+const CONTENT_PROPS: GuidanceBlockProps = {
+  ...GENERIC_PROPS,
+  content: (
+    <>
+      <Tag>Early Access</Tag>
+      <Heading variant="heading-3">{TEXT_PROPS.text.title}</Heading>
+      <Text variant="body">{TEXT_PROPS.text.description}</Text>
+    </>
+  ),
+}
+
+const StickerSheetTemplate: StickerSheetStory = {
+  render: ({ isReversed }) => (
+    <StickerSheet isReversed={isReversed}>
+      <StickerSheet.Body>
+        <StickerSheet.Row rowTitle="Default">
+          <GuidanceBlock {...TEXT_PROPS} />
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="Expert advice">
+          <GuidanceBlock variant="expert-advice" {...TEXT_PROPS} />
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="No arrow">
+          <GuidanceBlock withActionButtonArrow={false} {...TEXT_PROPS} />
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="Custom Content">
+          <GuidanceBlock {...CONTENT_PROPS} />
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="Tooltip">
+          <GuidanceBlock
+            {...TEXT_PROPS}
+            actions={{
+              primary: {
+                ...GENERIC_PROPS.actions.primary,
+                tooltip: {
+                  text: "Opens in a new tab",
+                  mood: "cautionary",
+                  isInitiallyVisible: true,
+                },
+              },
+            }}
+          />
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="Scene Illustration">
+          <GuidanceBlock
+            {...TEXT_PROPS}
+            illustration={<EmptyStatesPositive alt="" />}
+            illustrationType="scene"
+          />
+        </StickerSheet.Row>
+        <StickerSheet.Row rowTitle="No Max Width">
+          <GuidanceBlock {...TEXT_PROPS} noMaxWidth />
+        </StickerSheet.Row>
+      </StickerSheet.Body>
+    </StickerSheet>
+  ),
+}
+
+export const StickerSheetDefault: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: "Sticker Sheet (Default)",
+}
+
+export const StickerSheetRTL: StickerSheetStory = {
+  ...StickerSheetTemplate,
+  name: "Sticker Sheet (RTL)",
+  parameters: {
+    textDirection: "rtl",
+  },
+}

package/src/__containers__/GuidanceBlock/v2/_docs/GuidanceBlock.stories.tsx

@@ -0,0 +1,152 @@
+import React from "react"
+import { Meta, StoryObj } from "@storybook/react"
+import { Heading } from "~components/Heading"
+import {
+  BrandMomentPositiveOutro,
+  Informative,
+  SkillsCoachEssentialFeedback,
+} from "~components/Illustration"
+import { Text } from "~components/Text"
+import { GuidanceBlock } from "../index"
+
+const ContentComponent = (): JSX.Element => (
+  <>
+    <Heading tag="h3" variant="heading-3">
+      This is the Guidance block title
+    </Heading>
+    <Text variant="body">
+      Mussum Ipsum, cacilds vidis litro abertis. Suco de cevadiss, é um leite
+      divinis,
+    </Text>
+  </>
+)
+
+const defaultText = {
+  description:
+    "Mussum Ipsum, cacilds vidis litro abertis. Suco de cevadiss, é um leite divinis, qui tem lupuliz, matis, aguis e fermentis. Mé faiz elementum girarzis, nisi eros vermeio.",
+  title: "This is the Guidance block title",
+}
+
+const meta = {
+  title: "Containers/GuidanceBlock/v2",
+  component: GuidanceBlock,
+  args: {
+    layout: "default",
+    illustration: <Informative alt="" />,
+  },
+  argTypes: {
+    actions: {
+      control: false,
+    },
+    illustrationType: {
+      description:
+        "Sets the how the width and aspect ratio will respond to the Illustration passed in.",
+    },
+    illustration: {
+      control: { type: "radio" },
+      options: ["spot", "scene"],
+      mapping: {
+        spot: <Informative alt="" />,
+        scene: <BrandMomentPositiveOutro alt="" />,
+      },
+      description:
+        "This takes a scene scene or spot element, ie: `<Informative />`. This radio button implementation is a storybook only representation to toggle between the two illustration styles.",
+    },
+    content: {
+      description:
+        "If you need to render custom content inside of the `GuidanceBlock` that is more than just a title and description use this prop instead of the default `text` option.",
+    },
+  },
+} satisfies Meta<typeof GuidanceBlock>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  args: {
+    text: defaultText,
+  },
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: "shown",
+      },
+    },
+  },
+}
+
+export const Actions: Story = {
+  args: {
+    content: <ContentComponent />,
+    actions: {
+      primary: {
+        label: "Learn more",
+        onClick: () => alert("tada: 🎉"),
+      },
+      secondary: {
+        label: "Dismiss",
+        href: "#",
+      },
+    },
+  },
+}
+
+export const Tooltip: Story = {
+  args: {
+    content: <ContentComponent />,
+    actions: {
+      primary: {
+        label: "Hover me for a tooltip",
+        onClick: () => alert("tada: 🎉"),
+        tooltip: {
+          text: "Opens in a new tab",
+          mood: "cautionary",
+        },
+      },
+      secondary: {
+        label: "Dismiss",
+        href: "#",
+      },
+    },
+  },
+}
+
+export const CustomContent: Story = {
+  args: {
+    content: <ContentComponent />,
+  },
+}
+
+export const Stacked: Story = {
+  render: args => (
+    <div style={{ display: "flex", gap: "36px" }}>
+      <GuidanceBlock {...args} />
+      <GuidanceBlock {...args} />
+    </div>
+  ),
+  args: {
+    layout: "stacked",
+    content: <ContentComponent />,
+  },
+}
+
+export const SceneExample: Story = {
+  args: {
+    illustration: <SkillsCoachEssentialFeedback alt="" />,
+    illustrationType: "scene",
+    text: defaultText,
+  },
+}
+
+export const Variants: Story = {
+  render: args => (
+    <div className="flex flex-col gap-16">
+      <GuidanceBlock {...args} />
+      <GuidanceBlock variant="expert-advice" {...args} />
+    </div>
+  ),
+  args: {
+    text: defaultText,
+  },
+}

package/src/__containers__/GuidanceBlock/v2/index.ts

@@ -0,0 +1 @@
+export * from "./GuidanceBlock"

package/src/__containers__/v1.ts

@@ -0,0 +1 @@
+export * from "./GuidanceBlock/v1"

package/src/__containers__/v2.ts

@@ -0,0 +1 @@
+export * from "./GuidanceBlock/v2"

package/src/index.ts

@@ -20,7 +20,7 @@ export * from "./ErrorPage"
 export * from "./FieldGroup"
 export * from "./FieldMessage"
 export * from "./Filter"
-export * from "./GuidanceBlock"
+
 export * from "./Heading"
 export * from "./Icon"
 export * from "./Illustration"
@@ -61,3 +61,4 @@ export * from "./Workflow"
 export * from "./__overlays__/Tooltip/v1"
 export * from "./__actions__/Menu/v1"
 export * from "./__actions__/Button/v1"
+export * from "./__containers__/GuidanceBlock/v1"

package/v1/containers/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../../dist/cjs/containersV1.cjs",
+  "module": "../../dist/esm/containersV1.mjs",
+  "types": "../../dist/types/__containers__/v1.d.ts"
+}

package/v2/containers/package.json

@@ -0,0 +1,5 @@
+{
+  "main": "../../dist/cjs/containersV2.cjs",
+  "module": "../../dist/esm/containersV2.mjs",
+  "types": "../../dist/types/__containers__/v2.d.ts"
+}

package/dist/cjs/GuidanceBlock/GuidanceBlock.module.scss.cjs

@@ -1,33 +0,0 @@
-'use strict';
-
-var styles = {
-  "rightMargin": "GuidanceBlock-module_rightMargin__-iEFa",
-  "noRightMargin": "GuidanceBlock-module_noRightMargin__4Uy9N",
-  "banner": "GuidanceBlock-module_banner__FxKcd",
-  "noMaxWidth": "GuidanceBlock-module_noMaxWidth__UzHP1",
-  "illustrationWrapper": "GuidanceBlock-module_illustrationWrapper__AEljX",
-  "illustration": "GuidanceBlock-module_illustration__sU1Vu",
-  "hasSceneIllustration": "GuidanceBlock-module_hasSceneIllustration__tvFRD",
-  "descriptionContainer": "GuidanceBlock-module_descriptionContainer__aywtY",
-  "descriptionAndActions": "GuidanceBlock-module_descriptionAndActions__E5BcL",
-  "buttonContainer": "GuidanceBlock-module_buttonContainer__U2Hxn",
-  "hidden": "GuidanceBlock-module_hidden__CbgXn",
-  "headingWrapper": "GuidanceBlock-module_headingWrapper__zgVmA",
-  "cancel": "GuidanceBlock-module_cancel__UaIA-",
-  "icon": "GuidanceBlock-module_icon__y2xz8",
-  "disabled": "GuidanceBlock-module_disabled__Uhgsr",
-  "hover": "GuidanceBlock-module_hover__7V9x1",
-  "active": "GuidanceBlock-module_active__YJaZt",
-  "default": "GuidanceBlock-module_default__Ffblg",
-  "positive": "GuidanceBlock-module_positive__yENlT",
-  "negative": "GuidanceBlock-module_negative__E-Jvh",
-  "assertive": "GuidanceBlock-module_assertive__6PZlM",
-  "informative": "GuidanceBlock-module_informative__ZUH4j",
-  "cautionary": "GuidanceBlock-module_cautionary__sJ1CE",
-  "prominent": "GuidanceBlock-module_prominent__nn-r4",
-  "inline": "GuidanceBlock-module_inline__GwOWR",
-  "stacked": "GuidanceBlock-module_stacked__rDupX",
-  "centerContent": "GuidanceBlock-module_centerContent__m3IhB",
-  "smallScreenTextAlignment": "GuidanceBlock-module_smallScreenTextAlignment__oWufj"
-};
-module.exports = styles;

package/dist/esm/GuidanceBlock/GuidanceBlock.module.scss.mjs

@@ -1,31 +0,0 @@
-var styles = {
-  "rightMargin": "GuidanceBlock-module_rightMargin__-iEFa",
-  "noRightMargin": "GuidanceBlock-module_noRightMargin__4Uy9N",
-  "banner": "GuidanceBlock-module_banner__FxKcd",
-  "noMaxWidth": "GuidanceBlock-module_noMaxWidth__UzHP1",
-  "illustrationWrapper": "GuidanceBlock-module_illustrationWrapper__AEljX",
-  "illustration": "GuidanceBlock-module_illustration__sU1Vu",
-  "hasSceneIllustration": "GuidanceBlock-module_hasSceneIllustration__tvFRD",
-  "descriptionContainer": "GuidanceBlock-module_descriptionContainer__aywtY",
-  "descriptionAndActions": "GuidanceBlock-module_descriptionAndActions__E5BcL",
-  "buttonContainer": "GuidanceBlock-module_buttonContainer__U2Hxn",
-  "hidden": "GuidanceBlock-module_hidden__CbgXn",
-  "headingWrapper": "GuidanceBlock-module_headingWrapper__zgVmA",
-  "cancel": "GuidanceBlock-module_cancel__UaIA-",
-  "icon": "GuidanceBlock-module_icon__y2xz8",
-  "disabled": "GuidanceBlock-module_disabled__Uhgsr",
-  "hover": "GuidanceBlock-module_hover__7V9x1",
-  "active": "GuidanceBlock-module_active__YJaZt",
-  "default": "GuidanceBlock-module_default__Ffblg",
-  "positive": "GuidanceBlock-module_positive__yENlT",
-  "negative": "GuidanceBlock-module_negative__E-Jvh",
-  "assertive": "GuidanceBlock-module_assertive__6PZlM",
-  "informative": "GuidanceBlock-module_informative__ZUH4j",
-  "cautionary": "GuidanceBlock-module_cautionary__sJ1CE",
-  "prominent": "GuidanceBlock-module_prominent__nn-r4",
-  "inline": "GuidanceBlock-module_inline__GwOWR",
-  "stacked": "GuidanceBlock-module_stacked__rDupX",
-  "centerContent": "GuidanceBlock-module_centerContent__m3IhB",
-  "smallScreenTextAlignment": "GuidanceBlock-module_smallScreenTextAlignment__oWufj"
-};
-export { styles as default };

package/dist/types/Tile/subcomponents/GenericTile/types.d.ts

@@ -1,2 +0,0 @@
-export declare const moodsList: readonly ["positive", "informative", "cautionary", "assertive", "negative", "prominent"];
-export type Moods = (typeof moodsList)[number];