Add message promotions to lg-chat (#3149)

* Spacious message promotions

* Compact message promotions

* Promotions callback handler, tests, md links in new tab.

* Promotion link as external learnmore

* Cleanup

* Add stories for promotions, make link inline, update README

* Run changeset

* Update README based on recent changes

* Run linter

* Apply suggestions from code review

Co-authored-by: Stephen Lee <[email protected]>

* PR review: README improvements

* PR review: Remove promotions from spacious msg variant

* PR review: styling, Badge component, test with Chromatic, rm unused items

* Require promotion URL

* Actually support promotions darkmode [REAL]

* Center text / badge

* Rename onPromotionClick and Update message README

* Fix table

* Removing obvious info from README

* Removing obvious info from README

---------

Co-authored-by: Stephen Lee <[email protected]>

Author: hschawe

.changeset/dirty-monkeys-camp.md

@@ -0,0 +1,5 @@
+---
+'@lg-chat/message': minor
+---
+
+Add `Message.Promotion` as `Message` subcomponent for promotional content

chat/message/README.md

@@ -61,7 +61,7 @@ return (
 
 ### Compound Components
 
-The `Message` component uses a compound component pattern, allowing you to compose different parts of a message using subcomponents like `Message.Actions`, `Message.Links`, and `Message.VerifiedBanner`.
+The `Message` component uses a compound component pattern, allowing you to compose different parts of a message using subcomponents like `Message.Actions`, `Message.Links`, `Message.Promotion`, and `Message.VerifiedBanner`.
 
 **Note 1:** All compound components only render in the `compact` variant.  
 **Note 2:** The layout and order of compound components are enforced by the `Message` component itself. Even if you change the order of subcomponents in your JSX, they will be rendered in the correct, intended order within the message bubble. This ensures consistent UI and accessibility regardless of how you compose your message children.
@@ -155,6 +155,33 @@ const MessageWithLinks = () => {
 };
 ```
 
+### Message.Promotion
+
+```tsx
+import React from 'react';
+import {
+  LeafyGreenChatProvider,
+  Variant,
+} from '@lg-chat/leafygreen-chat-provider';
+import { Message } from '@lg-chat/message';
+
+const MessageWithPromotion = () => {
+  const handlePromotionClick = () => console.log('Promotion clicked');
+
+  return (
+    <LeafyGreenChatProvider variant={Variant.Compact}>
+      <Message isSender={false} messageBody="Test message">
+        <Message.Promotion
+          promotionText="Go learn more about this skill!"
+          promotionUrl="https://learn.mongodb.com/skills"
+          onPromotionLinkClick={handlePromotionClick}
+        />
+      </Message>
+    </LeafyGreenChatProvider>
+  );
+};
+```
+
 ### Message.VerifiedBanner
 
 ```tsx
@@ -223,10 +250,16 @@ const Example = () => {
   ];
 
   const handleLinkClick = () => console.log('Link clicked');
+  const handlePromotionClick = () => console.log('Promotion clicked');
 
   return (
     <LeafyGreenChatProvider variant={Variant.Compact}>
       <Message isSender={false} messageBody="Test message">
+        <Message.Promotion
+          promotionText="Go learn more about this skill!"
+          promotionUrl="https://learn.mongodb.com/skills"
+          onPromotionLinkClick={handlePromotionClick}
+        />
         <Message.Actions
           onClickCopy={handleCopy}
           onClickRetry={handleRetry}
@@ -286,6 +319,15 @@ const Example = () => {
 | `onLinkClick` _(optional)_ | `({ children: string }) => void` | A callback function that is called when any link is clicked. |                       |
 | `...`                      | `HTMLElementProps<'div'>`        | Props spread on the root element                             |                       |
 
+### Message.Promotion
+
+| Prop                                | Type                      | Description                              | Default |
+| ----------------------------------- | ------------------------- | ---------------------------------------- | ------- |
+| `promotionText`                     | `string`                  | Promotion text content.                  |         |
+| `promotionUrl`                      | `string`                  | Promotion URL for the "Learn More" link. |         |
+| `onPromotionLinkClick` _(optional)_ | `() => void`              | Promotion onClick callback handler.      |         |
+| `...`                               | `HTMLElementProps<'div'>` | Props spread on the root element         |         |
+
 ### Message.VerifiedBanner
 
 | Prop                        | Type     | Description                                       | Default |
@@ -361,6 +403,10 @@ The component manages its own internal state for:
 
 - Expansion state: Controls whether the links section is expanded or collapsed
 
+### Message.Promotion
+
+The `MessagePromotion` component displays promotional content with an award icon and "Learn More" link.
+
 ### Message.VerifiedBanner
 
 The `VerifiedBanner` component displays verification information for messages.

chat/message/package.json

@@ -15,6 +15,7 @@
   },
   "dependencies": {
     "@leafygreen-ui/avatar": "workspace:^",
+    "@leafygreen-ui/badge": "workspace:^",
     "@leafygreen-ui/banner": "workspace:^",
     "@leafygreen-ui/emotion": "workspace:^",
     "@leafygreen-ui/hooks": "workspace:^",

chat/message/src/Message.stories.tsx

@@ -118,6 +118,15 @@ const getLinksChild = () => (
   />
 );
 
+const getPromotionChild = () => (
+  <Message.Promotion
+    promotionText="Go learn more about this skill!"
+    promotionUrl="https://learn.mongodb.com/skills"
+    // eslint-disable-next-line no-console
+    onPromotionLinkClick={() => console.log('Promotion clicked')}
+  />
+);
+
 const meta: StoryMetaType<typeof Message> = {
   title: 'Composition/Chat/Message',
   component: Message,
@@ -282,13 +291,24 @@ export const WithMessageLinksExpanded: StoryObj<MessageStoryProps> = {
   },
 };
 
+export const WithPromotion: StoryObj<MessageStoryProps> = {
+  render: Template,
+  args: {
+    children: getPromotionChild(),
+    isSender: false,
+    messageBody: ASSISTANT_TEXT,
+  },
+};
+
 export const WithAllSubComponents: StoryObj<MessageStoryProps> = {
   render: Template,
   args: {
+    variant: Variant.Compact,
     children: (
       <>
         {getActionsChild()}
         {getLinksChild()}
+        {getPromotionChild()}
         {getVerifiedBannerChild()}
       </>
     ),

chat/message/src/Message/CompactMessage.tsx

@@ -45,6 +45,10 @@ export const CompactMessage = forwardRef<HTMLDivElement, MessageProps>(
       MessageSubcomponentProperty.VerifiedBanner,
     );
     const links = findChild(children, MessageSubcomponentProperty.Links);
+    const promotion = findChild(
+      children,
+      MessageSubcomponentProperty.Promotion,
+    );
 
     // Filter out subcomponents from children
     const remainingChildren = filterChildren(
@@ -82,6 +86,7 @@ export const CompactMessage = forwardRef<HTMLDivElement, MessageProps>(
           >
             {messageBody ?? ''}
           </MessageContent>
+          {promotion}
           {actions}
           {verifiedBanner}
           {links}

chat/message/src/Message/Message.tsx

@@ -13,13 +13,15 @@ import { MessageActions } from '../MessageActions';
 import { MessageVerifiedBanner } from '../MessageBanner';
 import { MessageContext } from '../MessageContext';
 import { MessageLinks } from '../MessageLinks';
+import { MessagePromotion } from '../MessagePromotion';
 
 import { CompactMessage } from './CompactMessage';
 import {
   type ActionsType,
   type LinksType,
   type MessageProps,
   MessageSubcomponentProperty,
+  type PromotionType,
   type VerifiedBannerType,
 } from './Message.types';
 import { SpaciousMessage } from './SpaciousMessage';
@@ -108,8 +110,12 @@ Links[MessageSubcomponentProperty.Links] = true;
 const VerifiedBanner = MessageVerifiedBanner as VerifiedBannerType;
 VerifiedBanner[MessageSubcomponentProperty.VerifiedBanner] = true;
 
+const Promotion = MessagePromotion as PromotionType;
+Promotion[MessageSubcomponentProperty.Promotion] = true;
+
 export const Message = Object.assign(BaseMessage, {
   Actions,
   Links,
   VerifiedBanner,
+  Promotion,
 });

chat/message/src/Message/Message.types.ts

@@ -12,6 +12,7 @@ import {
 import { type MessageContainerProps } from '../MessageContainer';
 import { type MessageContentProps } from '../MessageContent';
 import { type MessageLinksProps } from '../MessageLinks';
+import { type MessagePromotionProps } from '../MessagePromotion';
 
 export const Align = {
   Right: 'right',
@@ -115,6 +116,7 @@ export const MessageSubcomponentProperty = {
   Actions: 'isLGMessageActions',
   VerifiedBanner: 'isLGMessageVerifiedBanner',
   Links: 'isLGMessageLinks',
+  Promotion: 'isPromotion',
 } as const;
 
 /**
@@ -135,3 +137,7 @@ export type VerifiedBannerType =
   ForwardRefExoticComponent<MessageVerifiedBannerProps> & {
     [MessageSubcomponentProperty.VerifiedBanner]?: boolean;
   };
+
+export type PromotionType = ForwardRefExoticComponent<MessagePromotionProps> & {
+  [MessageSubcomponentProperty.Promotion]?: boolean;
+};

chat/message/src/MessagePromotion/MessagePromotion.spec.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+
+import { MessagePromotion, type MessagePromotionProps } from '.';
+
+const defaultProps: MessagePromotionProps = {
+  promotionText: 'Go learn a new skill!',
+  promotionUrl: 'https://learn.mongodb.com/skills',
+};
+
+const renderMessagePromotion = (props: Partial<MessagePromotionProps> = {}) => {
+  const { container } = render(
+    <MessagePromotion
+      data-testid="message-promotion"
+      {...defaultProps}
+      {...props}
+    />,
+  );
+  return { container };
+};
+
+describe('MessagePromotion', () => {
+  describe('a11y', () => {
+    test('does not have basic accessibility issues', async () => {
+      const { container } = renderMessagePromotion();
+      const results = await axe(container);
+      expect(results).toHaveNoViolations();
+    });
+  });
+
+  describe('rendering', () => {
+    test('renders promotion text & link', () => {
+      const promotionText = 'This is a test promotion message';
+      renderMessagePromotion({
+        promotionText,
+        promotionUrl: 'https://learn.mongodb.com/skills',
+      });
+
+      expect(screen.getByText(promotionText)).toBeInTheDocument();
+      expect(screen.getByText('Learn More')).toBeInTheDocument();
+    });
+  });
+
+  describe('callback handling', () => {
+    test('onPromotionLinkClick is called when promotion element is clicked', async () => {
+      const mockOnClick = jest.fn();
+
+      renderMessagePromotion({
+        ...defaultProps,
+        onPromotionLinkClick: mockOnClick,
+      });
+
+      const learnMoreLink = screen.getByText('Learn More');
+      await userEvent.click(learnMoreLink);
+
+      expect(mockOnClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('onPromotionLinkClick is not required', () => {
+      expect(() => {
+        renderMessagePromotion({
+          ...defaultProps,
+          onPromotionLinkClick: undefined,
+        });
+      }).not.toThrow();
+    });
+  });
+});

chat/message/src/MessagePromotion/MessagePromotion.styles.ts

@@ -0,0 +1,21 @@
+import { css } from '@leafygreen-ui/emotion';
+import { spacing } from '@leafygreen-ui/tokens';
+
+const BADGE_HEIGHT = spacing[600];
+const BADGE_WIDTH = spacing[900];
+
+export const promotionContainerStyles = css`
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 0px ${spacing[200]}px;
+`;
+
+export const badgeStyles = css`
+  display: flex;
+  flex-direction: row;
+  justify-content: center;
+
+  width: ${BADGE_WIDTH}px;
+  height: ${BADGE_HEIGHT}px;
+`;

chat/message/src/MessagePromotion/MessagePromotion.tsx

@@ -0,0 +1,49 @@
+import React from 'react';
+
+import Badge, { Variant } from '@leafygreen-ui/badge';
+import Icon from '@leafygreen-ui/icon';
+import LeafyGreenProvider, {
+  useDarkMode,
+} from '@leafygreen-ui/leafygreen-provider';
+import { Body, Link } from '@leafygreen-ui/typography';
+
+import {
+  badgeStyles,
+  promotionContainerStyles,
+} from './MessagePromotion.styles';
+import { type MessagePromotionProps } from './MessagePromotion.types';
+
+/**
+ * Renders promotional content with an award icon and "Learn More" link.
+ *
+ * @returns The rendered promotional message component.
+ */
+export function MessagePromotion({
+  promotionText,
+  promotionUrl,
+  onPromotionLinkClick,
+  darkMode: darkModeProp,
+  ...rest
+}: MessagePromotionProps) {
+  const { darkMode } = useDarkMode(darkModeProp);
+  return (
+    <LeafyGreenProvider darkMode={darkMode}>
+      <div className={promotionContainerStyles}>
+        <div>
+          <Badge variant={Variant.Green} className={badgeStyles}>
+            <Icon glyph="Award" />
+          </Badge>
+        </div>
+        <Body as="span" {...rest}>
+          {promotionText}
+          <>
+            {' '}
+            <Link href={promotionUrl} onClick={onPromotionLinkClick}>
+              Learn More
+            </Link>
+          </>
+        </Body>
+      </div>
+    </LeafyGreenProvider>
+  );
+}