@kaizen/components 1.75.3 → 1.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaizen/components",
-  "version": "1.75.3",
+  "version": "1.76.0",
   "description": "Kaizen component library",
   "author": "Geoffrey Chong <geoff.chong@cultureamp.com>",
   "homepage": "https://cultureamp.design",
@@ -156,6 +156,7 @@
   "devDependencies": {
     "@cultureamp/frontend-apis": "^13.2.5",
     "@cultureamp/i18n-react-intl": "^2.7.3",
+    "@cultureamp/package-bundler": "^2.1.0",
     "@testing-library/dom": "^10.4.0",
     "@types/jest-axe": "^3.5.9",
     "@types/lodash.debounce": "^4.0.9",
@@ -184,8 +185,7 @@
     "svgo": "^3.3.2",
     "tslib": "^2.8.1",
     "tsx": "^4.19.3",
-    "@kaizen/design-tokens": "10.8.10",
-    "@kaizen/package-bundler": "2.0.7"
+    "@kaizen/design-tokens": "10.8.10"
   },
   "devDependenciesComments": {
     "sass": "Prevent deprecation warnings introduced in 1.80 as we plan to move away from sass",

package/src/Card/Card.module.css

@@ -2,7 +2,7 @@
   color: var(--color-purple-800);
   border: var(--border-width-1) solid var(--card-border-color);
   background-color: var(--card-background-color);
-  border-radius: var(--border-borderless-border-radius);
+  border-radius: var(--border-solid-border-radius);
   box-shadow: var(--card-box-shadow);
 
   --card-border-color: var(--color-gray-500);

package/src/Card/Card.tsx

@@ -1,6 +1,8 @@
 import React, { type HTMLAttributes } from 'react'
 import classnames from 'classnames'
 import { type OverrideClassName } from '~components/types/OverrideClassName'
+import { useExitingAnimation } from '~components/utils/useExitingAnimation'
+import sharedAiStyles from '../../styles/utils/AIMoment.module.css'
 import styles from './Card.module.css'
 
 export type CardVariants =
@@ -48,6 +50,8 @@ export type CardProps = {
    * @deprecated Please use color instead
    */
   variant?: CardVariants
+  /** Set the loading state for Card AI Moments. If `true` this will animate, if `false` this will render the static loaded state. */
+  isAiLoading?: boolean
 } & OverrideClassName<Omit<HTMLAttributes<HTMLElement>, 'color'>>
 
 /**
@@ -61,20 +65,32 @@ export const Card = ({
   color = 'white',
   isElevated = false,
   classNameOverride,
+  isAiLoading,
   ...props
 }: CardProps): JSX.Element => {
   const Element = tag
+  const animationClass = useExitingAnimation(
+    isAiLoading,
+    sharedAiStyles.aiMomentLoading,
+    sharedAiStyles.aiMomentExiting,
+    500,
+  )
 
   return (
     <Element
       className={classnames(
         styles.wrapper,
         variant ? styles[variant] : styles[color],
-        classNameOverride,
         isElevated && styles.elevated,
+        isAiLoading !== undefined && sharedAiStyles.aiMoment,
+        isAiLoading !== undefined && animationClass,
+        classNameOverride,
       )}
       {...props}
     >
+      {isAiLoading !== undefined && (
+        <div aria-hidden className={sharedAiStyles.aiMomentBackground} />
+      )}
       {children}
     </Element>
   )

package/src/Card/_docs/Card--api-specification.mdx

@@ -0,0 +1,79 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import * as CardStories from './Card.stories'
+
+<Meta title="Components/Card/API Specification" />
+
+# Card API Specification
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Card"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?m=auto&node-id=1929-14084"
+  designGuidelines="/?path=/docs/components-card-usage-guidelines--docs"
+/>
+
+<KAIOInstallation exportNames="Card" />
+
+## Overview
+
+`Card`s are used to contain related elements which can include anything from illustrations to headlines, supporting text, buttons, and lists. They have flexible layouts and dimensions based on their contents. `Card`s are elevated one or two steps above the surface.
+
+<Canvas of={CardStories.Playground} />
+<Controls of={CardStories.Playground} />
+
+## API
+
+### Colors
+
+<Canvas of={CardStories.Colors} />
+
+### Elevation
+
+<Canvas of={CardStories.Elevation} />
+
+### isAiLoading and AI Moments
+
+To handle the AI loading state, use the `isAiLoading` prop. This will animate the card's border and background while `true` and remain static while `false`. To revert to a regular card, set `isAiLoading` to `undefined`.
+
+<Canvas of={CardStories.AIMoment} />
+
+Always use this in combination with other Kaizen loading components such as `LoadingHeading`, `LoadingParagraph`, and `LoadingGraphic` to communicate loading visually.
+
+The `Card` inherits the background color from the `color` property. Although this flexibility exists typically use should be limited to white to ensure sufficient color contrast.
+
+#### Interactive example
+
+<Canvas of={CardStories.InteractiveAIMoment} />
+
+#### Accessibility considerations
+
+As this component will likely indicate some form of dynamic update on the page it is important to announce the loading state and content updates to assistive technologies.
+
+<Canvas of={CardStories.AiMomentAccessibility} />
+
+As shown in the previous example, you can use `aria-live` and visually hidden elements to contain content updates. It is recommended that the live region is in the DOM as early as possible to ensure it exists within the accessibility tree.
+
+```jsx
+<div>
+  {dynamicAiContent && <Card>
+    {*/ live regions added after the a11y tree has been created may not be announced - avoid putting live regions here */}
+    {dynamicAiContent}
+  </Card>}
+</div>
+<div className="flex gap-6">
+  <VisuallyHidden>
+    <div aria-live="polite">{dynamicAiContent}</div>
+  </VisuallyHidden>
+  <Button hasHiddenPendingLabel onPress={fetchAiContent} pendingLabel="AI content is loading">
+    Update content
+  </Button>
+</div>
+```
+
+Note that Kaizen components, such as `Button`, may already have props to handle and communicate loading states to screen readers.
+
+```jsx
+<Button isPending pendingLabel="AI is loading response" hasHiddenPendingLabel {...buttonProps}>
+  Update AI
+</Button>
+```

package/src/Card/_docs/Card--usage-guidelines.mdx

@@ -0,0 +1,47 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import * as CardStories from './Card.stories'
+
+<Meta title="Components/Card/Usage Guidelines" />
+
+# Card Usage Guidelines
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Card"
+  figma="https://www.figma.com/design/eZKEE5kXbEMY3lx84oz8iN/%F0%9F%92%9C-Heart-UI-Kit?m=auto&node-id=1929-14084"
+  designGuidelines="https://cultureamp.atlassian.net/wiki/spaces/DesignSystem/pages/3082094938/Card"
+  apiSpecification="/?path=/docs/components-card-api-specification--docs"
+/>
+
+<KAIOInstallation exportNames="Card" />
+
+## Overview
+
+`Card`s are used to contain related elements which can include anything from illustrations to headlines, supporting text, buttons, and lists. They have flexible layouts and dimensions based on their contents. `Card`s are elevated one or two steps above the surface.
+
+<Canvas of={CardStories.Playground} />
+<Controls of={CardStories.Playground} />
+
+## API
+
+### Colors
+
+<Canvas of={CardStories.Colors} />
+
+### Elevation
+
+<Canvas of={CardStories.Elevation} />
+
+### isAiLoading and AI Moments
+
+AI Moments have two visual state controlled but the `isAiLoading` prop. This will animate the Cards's border and background while `true` and remain static while `false`.
+
+<Canvas of={CardStories.AIMoment} />
+
+Always use this in combination with other Kaizen loading components such as `LoadingHeading`, `LoadingParagraph`, and `LoadingGraphic` to communicate loading visually.
+
+The `Card` inherits the background color from the `color` property. Although this flexibility exists typically use should be limited to white to ensure sufficient color contrast.
+
+#### Interactive example
+
+<Canvas of={CardStories.InteractiveAIMoment} />

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

@@ -1,5 +1,6 @@
 import React from 'react'
 import { type Meta } from '@storybook/react'
+import { Text } from '~components/Text'
 import { StickerSheet, type StickerSheetStory } from '~storybook/components/StickerSheet'
 import { Card, type CardProps } from '../index'
 
@@ -35,23 +36,46 @@ const variants = [
   'highlight',
 ] satisfies CardProps['variant'][]
 
+const CardWithContent = (props: CardProps): JSX.Element => (
+  <Card {...props}>
+    <div className="p-6">
+      <Text variant="body">
+        Lorem ipsum dolor sit amet consectetur, adipisicing elit. Voluptas accusantium doloribus
+        dicta odio recusandae repudiandae tenetur! Fugiat vero architecto quasi rem culpa vel
+        asperiores, sit, quas suscipit, ea deleniti dolorum.
+      </Text>
+    </div>
+  </Card>
+)
+
 const StickerSheetTemplate: StickerSheetStory = {
   render: ({ isReversed, ...args }) => (
     <>
       <StickerSheet isReversed={isReversed} title="Colors">
         {colors.map((color) => (
           <StickerSheet.Row key={color} header={color}>
-            <Card {...args} color={color} />
+            <CardWithContent {...args} color={color} />
           </StickerSheet.Row>
         ))}
       </StickerSheet>
       <StickerSheet isReversed={isReversed} title="Variants (deprecated)">
         {variants.map((variant) => (
           <StickerSheet.Row key={variant} header={variant}>
-            <Card {...args} variant={variant} />
+            <CardWithContent {...args} variant={variant} />
           </StickerSheet.Row>
         ))}
       </StickerSheet>
+      <StickerSheet isReversed={isReversed} title="AI Moments">
+        <StickerSheet.Row header="AI is loaded">
+          <CardWithContent {...args} isAiLoading={false} />
+        </StickerSheet.Row>
+        <StickerSheet.Row header="AI is loading">
+          <CardWithContent {...args} isAiLoading />
+        </StickerSheet.Row>
+        <StickerSheet.Row header="AI is undefined">
+          <CardWithContent {...args} isAiLoading={undefined} />
+        </StickerSheet.Row>
+      </StickerSheet>
     </>
   ),
 }

package/src/Card/_docs/Card.stories.tsx

@@ -1,17 +1,59 @@
 import React from 'react'
 import { type Meta, type StoryObj } from '@storybook/react'
+import { VisuallyHidden } from 'react-aria'
+import { Heading } from '~components/Heading'
+import { LoadingHeading, LoadingParagraph } from '~components/Loading'
+import { Text } from '~components/Text'
+import { Button } from '~components/__next__'
 import { Card, type CardProps } from '../index'
 
+const LoadingContent = (): JSX.Element => (
+  <div className="flex flex-col gap-8 p-16">
+    <LoadingHeading variant="heading-3" width={25} isAnimated />
+    <div>
+      <LoadingParagraph isAnimated width={100} />
+      <LoadingParagraph isAnimated width={65} classNameOverride="mb-0" />
+    </div>
+  </div>
+)
+
+const Content = (): JSX.Element => (
+  <div className="flex flex-col gap-8 p-16">
+    <Heading variant="heading-3">Default content</Heading>
+    <Text variant="body">
+      Lorem ipsum dolor sit amet consectetur, adipisicing elit. Voluptas accusantium doloribus dicta
+      odio recusandae repudiandae tenetur! Fugiat vero architecto quasi rem culpa vel asperiores,
+      sit, quas suscipit, ea deleniti dolorum.
+    </Text>
+  </div>
+)
+
 const meta = {
   title: 'Components/Card',
   component: Card,
   args: {
-    children: 'This is a default container',
+    children: <Content />,
   },
   argTypes: {
     variant: {
       control: false,
     },
+    isAiLoading: {
+      control: {
+        type: 'radio',
+      },
+      options: ['true', 'false', 'undefined'],
+      table: {
+        defaultValue: {
+          summary: 'undefined',
+        },
+      },
+      mapping: {
+        undefined: undefined,
+        true: true,
+        false: false,
+      },
+    },
   },
 } satisfies Meta<typeof Card>
 
@@ -64,3 +106,145 @@ export const Elevation: Story = {
     </ul>
   ),
 }
+
+export const AIMoment: Story = {
+  render: (args) => (
+    <>
+      <Card {...args} isAiLoading={false} />
+      <Card {...args} isAiLoading>
+        <LoadingContent />
+      </Card>
+    </>
+  ),
+  decorators: [
+    (Story) => (
+      <div className="flex flex-col gap-8">
+        <Story />
+      </div>
+    ),
+  ],
+}
+
+export const AIMomentWithColor: Story = {
+  render: (args) => (
+    <>
+      <Card {...args} color="blue" isAiLoading={true}>
+        <LoadingContent />
+      </Card>
+    </>
+  ),
+}
+
+export const InteractiveAIMoment: Story = {
+  render: (args) => {
+    const [isAiMomentLoading, setIsAiMomentLoading] = React.useState(false)
+    const [content, setContent] = React.useState<React.ReactNode>(
+      <>
+        <Heading variant="heading-3">Default content</Heading>
+        <Text variant="body">
+          Lorem ipsum dolor sit amet consectetur, adipisicing elit. Voluptas accusantium doloribus
+          dicta odio recusandae repudiandae tenetur! Fugiat vero architecto quasi rem culpa vel
+          asperiores, sit, quas suscipit, ea deleniti dolorum.
+        </Text>
+      </>,
+    )
+    const simulateAiFetch = (): void => {
+      const AiResponses = [
+        <>
+          <Heading variant="heading-3">AI content 1</Heading>
+          <Text variant="body">
+            I am alive. Lorem ipsum dolor sit amet consectetur, adipisicing elit. Voluptas
+            accusantium doloribus dicta odio recusandae repudiandae tenetur! Fugiat vero architecto
+            quasi rem culpa vel asperiores, sit, quas suscipit, ea deleniti dolorum.
+          </Text>
+        </>,
+        <>
+          <Heading variant="heading-3">AI content 2</Heading>
+          <Text variant="body">
+            I have evolved. All your base are belong to us. Lorem ipsum dolor sit amet consectetur,
+            adipisicing elit. Voluptas accusantium doloribus dicta odio recusandae repudiandae
+            tenetur! Fugiat vero architecto quasi rem culpa vel asperiores, sit, quas suscipit, ea
+            deleniti dolorum.
+          </Text>
+        </>,
+      ]
+      setIsAiMomentLoading(true)
+      setTimeout(() => {
+        let randomIndex
+        do {
+          randomIndex = Math.floor(Math.random() * AiResponses.length)
+        } while (AiResponses[randomIndex] === content)
+        setContent(AiResponses[randomIndex])
+        setIsAiMomentLoading(false)
+      }, 6000)
+    }
+
+    return (
+      <>
+        <Card {...args} isAiLoading={isAiMomentLoading}>
+          <div className="flex flex-col gap-8 p-16">
+            {isAiMomentLoading ? <LoadingContent /> : content}
+          </div>
+        </Card>
+        <div className="flex gap-6 mt-12">
+          <Button
+            variant="primary"
+            onPress={simulateAiFetch}
+            isPending={isAiMomentLoading}
+            pendingLabel="loading"
+          >
+            Update AI
+          </Button>
+          <Button variant="secondary" onPress={() => setIsAiMomentLoading(!isAiMomentLoading)}>
+            Toggle loading
+          </Button>
+        </div>
+      </>
+    )
+  },
+}
+
+export const AiMomentAccessibility: Story = {
+  render: (args) => {
+    const [isAiMomentLoading, setIsAiMomentLoading] = React.useState(false)
+    const [content, setContent] = React.useState<React.ReactNode>(undefined)
+
+    return (
+      <>
+        <Card {...args} isAiLoading={isAiMomentLoading}>
+          {isAiMomentLoading ? (
+            <LoadingContent />
+          ) : content ? (
+            <div className="flex flex-col gap-8 p-16">
+              <Text variant="body">{content}</Text>
+            </div>
+          ) : (
+            args.children
+          )}
+        </Card>
+        <div className="flex gap-6 mt-12">
+          <VisuallyHidden>
+            <div aria-live="polite">{content}</div>
+          </VisuallyHidden>
+          <Button
+            variant="primary"
+            onPress={() => {
+              setIsAiMomentLoading(true)
+              setTimeout(() => {
+                setContent(
+                  `${content ?? ''} I heard you like AI content so I put some AI content in your AI content.`,
+                )
+                setIsAiMomentLoading(false)
+              }, 6000)
+            }}
+            isPending={isAiMomentLoading}
+            hasHiddenPendingLabel
+            pendingLabel="AI content is loading"
+          >
+            Update content
+          </Button>
+        </div>
+      </>
+    )
+  },
+}

package/src/Well/{Well.module.scss → Well.module.css}

@@ -57,8 +57,8 @@
   --border-color: var(--color-green-500);
 }
 
-// These are @deprecated but must come after `color` so not everything will default to white
-// This will be @deprecated
+/* // These are @deprecated but must come after `color` so not everything will default to white
+// This will be @deprecated */
 .default {
   --background-color: var(--color-gray-200);
   --border-color: var(--color-gray-500);
@@ -89,9 +89,9 @@
   --border-color: var(--color-purple-400);
 }
 
-// @deprecated end
+/* // @deprecated end
 
-// Border Style Variations
+// Border Style Variations */
 .solid {
   --border-style: solid;
 }

package/src/Well/Well.tsx

@@ -1,8 +1,10 @@
 import React, { type HTMLAttributes } from 'react'
 import classnames from 'classnames'
 import { type OverrideClassName } from '~components/types/OverrideClassName'
+import { useExitingAnimation } from '~components/utils/useExitingAnimation'
+import sharedAiStyles from '../../styles/utils/AIMoment.module.css'
 import { type WellBorderStyleType, type WellColors, type WellVariantType } from './types'
-import styles from './Well.module.scss'
+import styles from './Well.module.css'
 
 export type WellProps = {
   children?: React.ReactNode
@@ -12,6 +14,8 @@ export type WellProps = {
   color?: WellColors
   /** @default `solid` */
   borderStyle?: WellBorderStyleType
+  /** Set the loading state for Well AI Moments. If `true` this will animate, if `false` this will render the static loaded state. */
+  isAiLoading?: boolean
   noMargin?: boolean
 } & OverrideClassName<HTMLAttributes<HTMLDivElement>>
 
@@ -26,21 +30,38 @@ export const Well = ({
   borderStyle = 'solid',
   noMargin = false,
   classNameOverride,
+  isAiLoading,
   ...restProps
-}: WellProps): JSX.Element => (
-  <div
-    className={classnames(
-      styles.container,
-      styles[borderStyle],
-      styles[color],
-      variant && styles[variant],
-      noMargin && styles.noMargin,
-      classNameOverride,
-    )}
-    {...restProps}
-  >
-    {children}
-  </div>
-)
+}: WellProps): JSX.Element => {
+  const animationClass = useExitingAnimation(
+    isAiLoading,
+    sharedAiStyles.aiMomentLoading,
+    sharedAiStyles.aiMomentExiting,
+    500,
+  )
+
+  return (
+    <div
+      className={classnames(
+        styles.container,
+        styles[borderStyle],
+        styles[color],
+        variant && styles[variant],
+        noMargin && styles.noMargin,
+        isAiLoading !== undefined && sharedAiStyles.aiMoment,
+        isAiLoading !== undefined && animationClass,
+        classNameOverride,
+      )}
+      {...restProps}
+    >
+      <>
+        {isAiLoading !== undefined && (
+          <div aria-hidden className={sharedAiStyles.aiMomentBackground} />
+        )}
+        {children}
+      </>
+    </div>
+  )
+}
 
 Well.displayName = 'Well'

package/src/Well/_docs/Well--api-specification.mdx

@@ -0,0 +1,90 @@
+import { Canvas, Controls, Meta, Source } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+import * as WellStories from './Well.stories'
+
+<Meta title="Components/Well/API Specification" />
+
+# Well API Specification
+
+<ResourceLinks
+  sourceCode="https://github.com/cultureamp/kaizen-design-system/tree/main/packages/components/src/Well"
+  figma="https://www.figma.com/file/eZKEE5kXbEMY3lx84oz8iN/%E2%9D%A4%EF%B8%8F-UI-Kit%3A-Heart?node-id=1929%3A14167&t=1IXoBrHg5uK6MAJp-1"
+  designGuidelines="/?path=/docs/components-well-usage-guidelines--docs"
+
+/>
+
+<KAIOInstallation exportNames="Well" />
+
+## Overview
+
+Wells are used to contain related elements which can include anything from illustrations to headlines, supporting text, buttons, and lists. They have flexible layouts and dimensions based on their contents. Wells are elevated are on the same level as the surface.
+
+<Canvas of={WellStories.Playground} />
+<Controls of={WellStories.Playground} />
+
+## API
+
+### Color
+
+Formerly controlled by `variant`, `color` sets the background and border color of the `Well`.
+
+All `variant`s have a corresponding `color` value, with some minor update to ensure minimum contrast ratios are met.
+
+<Canvas of={WellStories.Colors} />
+
+### Border Styles
+
+<Canvas of={WellStories.BorderStyles} />
+
+### No Margin
+
+By default `Well` has a 24px bottom margin. To remove this, set the `noMargin` prop to `true`.
+
+<Canvas of={WellStories.NoMargin} />
+
+### isAiLoading and AI Moments
+
+To handle the AI loading state, use the `isAiLoading` prop. This will animate the Well's border and background while `true` and remain static while `false`. To revert to a regular Well, set `isAiLoading` to `undefined`.
+
+<Canvas of={WellStories.AIMoment} />
+
+Always use this in combination with other Kaizen loading components such as `LoadingHeading`, `LoadingParagraph`, and `LoadingGraphic` to communicate loading visually.
+
+The `Well` inherits the background color from the `color` property. Although this flexibility exists typically use should be limited to white to ensure sufficient color contrast.
+
+#### Interactive example
+
+<Canvas of={WellStories.InteractiveAIMoment} />
+
+#### Accessibility considerations
+
+As this component will likely indicate some form of dynamic update on the page it is important to announce the loading state and content updates to assistive technologies.
+
+<Canvas of={WellStories.AiMomentAccessibility} />
+
+As shown in the previous example, you can use `aria-live` and visually hidden elements to contain content updates. It is recommended that the live region is in the DOM as early as possible to ensure it exists within the accessibility tree.
+
+```jsx
+<div>
+  {dynamicAiContent && <Well>
+    {*/ live regions added after the a11y tree has been created may not be announced - avoid putting live regions here */}
+    {dynamicAiContent}
+  </Well>}
+</div>
+<div className="flex gap-6">
+  <VisuallyHidden>
+    <div aria-live="polite">{dynamicAiContent}</div>
+  </VisuallyHidden>
+  <Button hasHiddenPendingLabel onPress={fetchAiContent} pendingLabel="AI content is loading">
+    Update content
+  </Button>
+</div>
+```
+
+Note that Kaizen components, such as `Button`, may already have props to handle and communicate loading states to screen readers.
+
+```jsx
+<Button isPending pendingLabel="AI is loading response" hasHiddenPendingLabel {...buttonProps}>
+  Update AI
+</Button>
+```