@transferwise/components 46.127.1 → 46.128.1

package/src/prompt/ActionPrompt/ActionPrompt.story.tsx

@@ -1,22 +1,11 @@
 import { ReactElement, useState } from 'react';
 import { Meta, StoryObj } from '@storybook/react-webpack5';
 import { fn } from 'storybook/test';
-import { Bank, Freeze, People } from '@transferwise/icons';
-import { ActionPrompt } from './ActionPrompt';
-import { lorem10 } from '../../test-utils';
-import Body from '../../body';
-import { action } from 'storybook/actions';
+import { Bank, Star, Travel, Briefcase } from '@transferwise/icons';
+import { lorem10, lorem20 } from '../../test-utils';
+import Button from '../../button';
 import Title from '../../title';
-import { withVariantConfig } from '../../../.storybook/helpers';
-
-const meta: Meta<typeof ActionPrompt> = {
-  title: 'Prompts/ActionPrompt',
-  component: ActionPrompt,
-  tags: ['new'],
-};
-
-export default meta;
-type Story = StoryObj<typeof ActionPrompt>;
+import { ActionPrompt, type ActionPromptProps } from './ActionPrompt';
 
 const withComponentGrid =
   ({ maxWidth = 'auto', gap = '1rem' } = {}) =>
@@ -37,151 +26,377 @@ const withComponentGrid =
     </div>
   );
 
-export const AllSentiments: Story = {
-  render: () => {
-    return (
-      <>
-        {(['negative', 'warning', 'neutral', 'success', 'proposition'] as const).map(
-          (sentiment) => (
-            <ActionPrompt
-              key={sentiment}
-              sentiment={sentiment}
-              title="Title"
-              description={lorem10}
-              action={{ label: 'Primary', onClick: fn() }}
-              actionSecondary={{ label: 'Secondary', onClick: fn() }}
-              className="m-b-2"
-              onDismiss={fn()}
-            />
-          ),
-        )}
-      </>
-    );
-  },
+const meta: Meta<typeof ActionPrompt> = {
+  title: 'Prompts/ActionPrompt',
+  component: ActionPrompt,
+  tags: ['new'],
   decorators: [withComponentGrid()],
+  args: {
+    title: 'Action Required',
+    description: 'Please complete the following action to continue.',
+    action: { label: 'Continue', onClick: fn() },
+  },
+  argTypes: {
+    sentiment: {
+      control: 'select',
+      options: ['success', 'negative', 'neutral', 'warning', 'proposition'],
+    },
+    title: {
+      control: 'text',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    description: {
+      control: 'text',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    media: {
+      control: false,
+      table: {
+        type: {
+          summary: 'ActionPromptMedia',
+          detail:
+            '{ imgSrc?: string; avatar?: { imgSrc?: string; profileName?: string; profileType?: string; asset?: ReactNode; badge?: { flagCode: string } }; aria-label?: string }',
+        },
+      },
+    },
+    action: {
+      control: false,
+      table: {
+        type: {
+          summary: 'ActionPromptAction',
+          detail: '{ label: ReactNode; onClick?: () => void; href?: string; target?: string }',
+        },
+      },
+    },
+    actionSecondary: {
+      control: false,
+      table: {
+        type: {
+          summary: 'ActionPromptActionSecondary',
+          detail: '{ label: ReactNode; onClick?: () => void; href?: string; target?: string }',
+        },
+      },
+    },
+  },
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ActionPrompt>;
+
+/**
+ * Convenience controls for previewing rich markup,
+ * not otherwise possible via Storybook
+ */
+type PreviewStoryArgs = ActionPromptProps & {
+  previewMedia: ActionPromptProps['media'];
+  previewOnDismiss: boolean;
+  previewSecondaryAction: boolean;
 };
 
-export const Mobile: Story = {
-  ...AllSentiments,
-  ...withVariantConfig(['mobile'], AllSentiments),
+const previewArgGroup = {
+  category: 'Storybook Preview options',
+  type: {
+    summary: undefined,
+  },
 };
 
-export const PrimaryActionOnly: Story = {
+const MEDIA_OPTIONS: Record<string, ActionPromptProps['media']> = {
+  undefined,
+  'Custom image (no badge)': { imgSrc: '../../wise-card.svg' },
+  'Avatar: Profile image': { avatar: { imgSrc: '../../avatar-rectangle-fox.webp' } },
+  'Avatar: Business (GB badge)': {
+    avatar: { profileType: 'BUSINESS', badge: { flagCode: 'GB' } },
+  },
+  'Avatar: Personal (EU badge)': {
+    avatar: { profileType: 'PERSONAL', badge: { flagCode: 'EU' } },
+  },
+  'Avatar: Icon (Bank)': { avatar: { asset: <Bank /> } },
+  'Avatar: Icon (Star)': { avatar: { asset: <Star /> } },
+  'Avatar: Icon (Travel)': { avatar: { asset: <Travel /> } },
+  'Avatar: Icon (Briefcase)': { avatar: { asset: <Briefcase /> } },
+  'Avatar: Initials': { avatar: { profileName: 'John Doe' } },
+};
+
+const previewArgTypes = {
+  previewMedia: {
+    name: 'Preview with `media`',
+    control: 'select',
+    options: [
+      'undefined',
+      'Custom image (no badge)',
+      'Avatar: Profile image',
+      'Avatar: Business (GB badge)',
+      'Avatar: Personal (EU badge)',
+      'Avatar: Icon (Bank)',
+      'Avatar: Icon (Star)',
+      'Avatar: Icon (Travel)',
+      'Avatar: Icon (Briefcase)',
+      'Avatar: Initials',
+    ],
+    mapping: MEDIA_OPTIONS,
+    table: previewArgGroup,
+  },
+  previewOnDismiss: {
+    name: 'Preview with `onDismiss`',
+    control: 'boolean',
+    table: previewArgGroup,
+  },
+  previewSecondaryAction: {
+    name: 'Preview with `actionSecondary`',
+    control: 'boolean',
+    table: previewArgGroup,
+  },
+} as const;
+
+const getPropsForPreview = (
+  args: PreviewStoryArgs,
+): [ActionPromptProps, Partial<ActionPromptProps>] => {
+  const { previewMedia, previewOnDismiss, previewSecondaryAction, ...props } = args;
+
+  return [
+    props,
+    {
+      media: previewMedia,
+      onDismiss: previewOnDismiss ? fn() : undefined,
+      actionSecondary: previewSecondaryAction ? { label: 'Cancel', onClick: fn() } : undefined,
+    },
+  ];
+};
+
+export const Playground: StoryObj<PreviewStoryArgs> = {
+  argTypes: {
+    sentiment: {
+      control: 'radio',
+      options: ['success', 'negative', 'neutral', 'warning', 'proposition'],
+    },
+    ...previewArgTypes,
+  },
   args: {
-    sentiment: 'proposition',
-    title: 'Payment successful',
-    description: 'Your money is on its way',
-    action: { label: 'View details', onClick: fn() },
-    onDismiss: fn(),
+    previewMedia: { avatar: undefined },
+    previewOnDismiss: true,
+    previewSecondaryAction: true,
+  },
+  render: (args: PreviewStoryArgs) => {
+    const [props, previewProps] = getPropsForPreview(args);
+    return <ActionPrompt {...props} {...previewProps} />;
   },
 };
 
-export const WithoutDescription: Story = {
-  render: () => {
-    return (
-      <>
-        <ActionPrompt
-          sentiment="warning"
-          title="Session expiring soon"
-          action={{ label: 'Stay logged in', onClick: fn() }}
-          actionSecondary={{ label: 'Log out', onClick: fn() }}
-          onDismiss={fn()}
-        />
+/**
+ * ActionPrompt supports multiple sentiments to communicate different types of messages:
+ * - `neutral` (default): General prompts
+ * - `success`: Success confirmations
+ * - `negative`: Error or critical actions
+ * - `warning`: Warning messages
+ * - `proposition`: Promotional or feature prompts
+ */
+export const Sentiments: Story = {
+  render: (args) => (
+    <>
+      {(['success', 'warning', 'negative', 'neutral', 'proposition'] as const).map((sentiment) => (
         <ActionPrompt
-          sentiment="success"
-          title="Session expiring soon"
-          action={{ label: 'Stay logged in', onClick: fn() }}
-        />
-        <ActionPrompt
-          title="Session expiring soon"
-          action={{ label: 'Stay logged in', onClick: fn() }}
+          key={sentiment}
+          sentiment={sentiment}
+          title={`${sentiment.charAt(0).toUpperCase() + sentiment.slice(1)} Action`}
+          description={lorem10}
+          action={{ label: 'Primary', onClick: fn() }}
+          actionSecondary={{ label: 'Secondary', onClick: fn() }}
         />
-      </>
-    );
-  },
-  decorators: [withComponentGrid()],
+      ))}
+    </>
+  ),
+};
+
+/**
+ * ActionPrompt can have just a primary action, or both primary and secondary actions.
+ */
+export const Actions: Story = {
+  render: () => (
+    <>
+      <ActionPrompt
+        sentiment="proposition"
+        title="Primary action only"
+        description="This prompt has only one action button."
+        action={{ label: 'Get started', onClick: fn() }}
+      />
+      <ActionPrompt
+        sentiment="warning"
+        title="Primary and secondary actions"
+        description="This prompt has both action buttons."
+        action={{ label: 'Confirm', onClick: fn() }}
+        actionSecondary={{ label: 'Cancel', onClick: fn() }}
+      />
+    </>
+  ),
 };
 
-export const Media: Story = {
+/**
+ * ActionPrompt supports various media types to enhance visual communication.
+ *
+ * **Default**: Each sentiment has a default status icon that appears when no media is provided.
+ *
+ * **Icon Overrides**: Replace default icons with custom images, avatars with images, avatars with initials,
+ * avatars with custom icons, or avatars with profile types and badges.
+ */
+export const MediaTypes: Story = {
   render: () => {
     return (
       <>
+        <Title type="title-body">Default</Title>
+        <ActionPrompt
+          sentiment="success"
+          title="Default status icon"
+          description="When no media is provided, the sentiment's default status icon is displayed."
+          action={{ label: 'Continue', onClick: fn() }}
+        />
+
+        <Title type="title-body">Icon Overrides</Title>
         <ActionPrompt
           sentiment="neutral"
           title="Custom image"
           description={lorem10}
           media={{ imgSrc: '../../wise-card.svg' }}
-          action={{ label: 'Invite now', onClick: fn() }}
+          action={{ label: 'View card', onClick: fn() }}
         />
         <ActionPrompt
           sentiment="neutral"
-          title="Profile Image"
+          title="Avatar with image"
           description={lorem10}
           media={{ avatar: { imgSrc: '../../avatar-rectangle-fox.webp' } }}
-          action={{ label: 'Invite now', onClick: fn() }}
+          action={{ label: 'View profile', onClick: fn() }}
         />
         <ActionPrompt
-          sentiment="proposition"
-          title="Business Profile"
+          sentiment="success"
+          title="Avatar with initials"
           description={lorem10}
-          media={{ avatar: { profileType: 'BUSINESS', badge: { flagCode: 'GB' } } }}
-          action={{ label: 'Invite now', onClick: fn() }}
+          media={{ avatar: { profileName: 'John Doe' } }}
+          action={{ label: 'Send invite', onClick: fn() }}
         />
         <ActionPrompt
-          sentiment="negative"
-          title="Personal Profile"
+          sentiment="warning"
+          title="Avatar with custom icon"
           description={lorem10}
-          media={{ avatar: { profileType: 'PERSONAL', badge: { flagCode: 'EU' } } }}
-          action={{ label: 'Invite now', onClick: fn() }}
+          media={{ avatar: { asset: <Bank /> } }}
+          action={{ label: 'Connect bank', onClick: fn() }}
         />
         <ActionPrompt
-          sentiment="warning"
-          title="Custom Icon"
+          sentiment="proposition"
+          title="Business profile with badge"
           description={lorem10}
-          media={{ avatar: { asset: <Bank /> } }}
-          action={{ label: 'Invite now', onClick: fn() }}
+          media={{ avatar: { profileType: 'BUSINESS', badge: { flagCode: 'GB' } } }}
+          action={{ label: 'Open account', onClick: fn() }}
         />
         <ActionPrompt
-          sentiment="success"
-          title="Initials"
+          sentiment="negative"
+          title="Personal profile with badge"
           description={lorem10}
-          media={{ avatar: { profileName: 'John Doe' } }}
-          action={{ label: 'Invite now', onClick: fn() }}
-          actionSecondary={{ label: 'Maybe later', onClick: fn() }}
+          media={{ avatar: { profileType: 'PERSONAL', badge: { flagCode: 'EU' } } }}
+          action={{ label: 'Verify', onClick: fn() }}
         />
       </>
     );
   },
-  decorators: [withComponentGrid()],
 };
 
-export const OnDismiss: Story = {
-  render: () => {
-    const [showNeutralPrompt, setShowNeutralPrompt] = useState(true);
-    const [showSuccessPrompt, setShowSuccessPrompt] = useState(true);
+/**
+ * When `onDismiss` is provided, a close button appears allowing users to dismiss the prompt.
+ * Note: The component itself is not automatically removed - you must handle state management.
+ */
+export const Dismissible: Story = {
+  render: (args) => {
+    const [showPrompt, setShowPrompt] = useState(true);
 
     return (
       <>
-        {showNeutralPrompt && (
+        {showPrompt ? (
           <ActionPrompt
             sentiment="proposition"
-            title="Payment successful"
-            description="Your money is on its way"
-            action={{ label: 'View details', onClick: fn() }}
-            className="m-b-2"
-            onDismiss={() => setShowNeutralPrompt(false)}
-          />
-        )}
-        {showSuccessPrompt && (
-          <ActionPrompt
-            sentiment="success"
-            title="Payment successful"
-            description="Your money is on its way"
-            action={{ label: 'View details', onClick: fn() }}
-            onDismiss={() => setShowSuccessPrompt(false)}
+            title="Special offer"
+            description="Get 50% off your next transfer!"
+            action={{ label: 'Claim now', onClick: fn() }}
+            onDismiss={() => setShowPrompt(false)}
           />
+        ) : (
+          <Button v2 onClick={() => setShowPrompt(true)}>
+            Show prompt again
+          </Button>
         )}
       </>
     );
   },
 };
+
+/**
+ * ActionPrompt adapts its layout based on available width. At narrow widths (mobile),
+ * the buttons stack vertically. At wider widths (desktop), they appear side by side.
+ */
+export const Responsiveness: Story = {
+  render: (args) => (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: '320px 480px',
+        gap: '1rem',
+        alignItems: 'start',
+      }}
+    >
+      <ActionPrompt
+        sentiment="proposition"
+        title="Stacked (320px)"
+        description={lorem10}
+        media={{ avatar: { asset: <Travel /> } }}
+        action={{ label: 'Primary action', onClick: fn() }}
+        actionSecondary={{ label: 'Secondary', onClick: fn() }}
+        onDismiss={fn()}
+      />
+      <ActionPrompt
+        sentiment="proposition"
+        title="Side-by-side (480px)"
+        description={lorem10}
+        media={{ avatar: { asset: <Travel /> } }}
+        action={{ label: 'Primary action', onClick: fn() }}
+        actionSecondary={{ label: 'Secondary', onClick: fn() }}
+        onDismiss={fn()}
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+};
+
+/**
+ * While the component itself will stretch to the full available width, the text container will be
+ * capped at `480px` to ensure optimal readability.
+ *
+ * [Visit wise.design](https://wise.design/components/info-prompt#writing-an-info-prompt) for guidance on writing effective prompt messages that are concise and easy to understand.
+ */
+export const ParagraphWidth: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  args: {
+    title: lorem10,
+    description: lorem20,
+    sentiment: 'success',
+    action: { label: 'View details', onClick: fn() },
+    onDismiss: () => {},
+  },
+};

package/src/prompt/ActionPrompt/ActionPrompt.test.story.tsx

@@ -1,13 +1,25 @@
+import { ReactElement } from 'react';
 import { Freeze, People } from '@transferwise/icons';
 import { action } from 'storybook/actions';
+import { fn } from 'storybook/test';
 import ActionPrompt from './ActionPrompt';
 import { Body, Title } from '../..';
-import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { StoryObj } from '@storybook/react-webpack5';
+import { allModes } from '../../../.storybook/modes';
+import { withVariantConfig } from '../../../.storybook/helpers';
+
+const withComponentGrid =
+  ({ gap = '1rem' } = {}) =>
+  (Story: () => ReactElement) => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap }}>
+      <Story />
+    </div>
+  );
 
 export default {
   title: 'Prompts/ActionPrompt/Tests',
   component: ActionPrompt,
-  tags: ['!manifest', '!autodocs'],
+  tags: ['!manifest', '!autodocs', 'new'],
 };
 
 type Story = StoryObj<typeof ActionPrompt>;
@@ -130,7 +142,7 @@ export const VariousA11yFeatures: Story = {
           sentiment="negative"
           media={{ avatar: { asset: <People /> } }}
           title="Sync contacts for a faster experience"
-          description="Find contacts on Wise — it’s simple, secure and you pick who you add."
+          description="Find contacts on Wise — it's simple, secure and you pick who you add."
           action={{
             label: 'Sync contacts',
             onClick: () => {
@@ -145,3 +157,74 @@ export const VariousA11yFeatures: Story = {
     );
   },
 };
+
+/**
+ * ActionPrompt can be shown with or without a description.
+ */
+export const WithoutDescription: Story = {
+  render: () => {
+    return (
+      <>
+        <ActionPrompt
+          sentiment="warning"
+          title="Session expiring soon"
+          action={{ label: 'Stay logged in', onClick: fn() }}
+          actionSecondary={{ label: 'Log out', onClick: fn() }}
+        />
+        <ActionPrompt
+          sentiment="success"
+          title="Payment successful"
+          action={{ label: 'View details', onClick: fn() }}
+        />
+        <ActionPrompt title="Quick action" action={{ label: 'Continue', onClick: fn() }} />
+      </>
+    );
+  },
+  decorators: [withComponentGrid()],
+};
+
+export const AllThemesAndSentiments: Story = {
+  render: () => {
+    return (
+      <>
+        {(['negative', 'warning', 'neutral', 'success', 'proposition'] as const).map(
+          (sentiment) => (
+            <ActionPrompt
+              key={sentiment}
+              sentiment={sentiment}
+              title={`${sentiment.charAt(0).toUpperCase() + sentiment.slice(1)} action`}
+              description="This demonstrates the prompt appearance in different themes."
+              action={{ label: 'Primary', onClick: fn() }}
+              actionSecondary={{ label: 'Secondary', onClick: fn() }}
+              onDismiss={fn()}
+            />
+          ),
+        )}
+      </>
+    );
+  },
+  decorators: [withComponentGrid({ gap: '1.5rem' })],
+  parameters: {
+    padding: '16px',
+    variants: ['default', 'dark', 'bright-green', 'forest-green'],
+    chromatic: {
+      dark: allModes.dark,
+      brightGreen: allModes.brightGreen,
+      forestGreen: allModes.forestGreen,
+    },
+  },
+};
+
+export const TinyScreen: Story = {
+  render: () => (
+    <ActionPrompt
+      sentiment="warning"
+      title="Complete your profile"
+      description="Add your business details to unlock all features and start sending money internationally."
+      action={{ label: 'Complete profile', onClick: fn() }}
+      actionSecondary={{ label: 'Remind me later', onClick: fn() }}
+      onDismiss={fn()}
+    />
+  ),
+  ...withVariantConfig(['400%']),
+};

package/src/prompt/ActionPrompt/ActionPrompt.tsx

@@ -34,6 +34,13 @@ export type ActionPromptProps = {
   'aria-label'?: AriaAttributes['aria-label'];
 } & Pick<PrimitivePromptProps, 'id' | 'className' | 'data-testid' | 'sentiment' | 'onDismiss'>;
 
+/**
+ * Use an action prompt for optional feedback that doesn't require immediate action, such as feature upsells, warnings, or suggestions. These prompts are typically used outside of core product flows (e.g., Launchpad, Recipient, or Transaction screens) and can be addressed at the user's convenience.
+ *
+ * If your message is about immediate user feedback (e.g., form submission errors, download failures, missing data warnings), use an [info prompt](https://storybook.wise.design/?path=/docs/prompts-infoprompt--docs) instead.
+ *
+ * Guidance can be found in the [design system](https://wise.design/components/action-prompt).
+ */
 export const ActionPrompt = ({
   sentiment = 'neutral',
   title,
@@ -55,7 +62,7 @@ export const ActionPrompt = ({
 
   const ariaLabelledByIds = [
     media['aria-hidden'] ? undefined : mediaId,
-    Boolean(ariaLabel) ? undefined : titleId,
+    ariaLabel ? undefined : titleId,
   ]
     .filter(Boolean)
     .join(' ');
@@ -104,7 +111,7 @@ export const ActionPrompt = ({
         id={mediaId}
         size={48}
         sentiment={sentiment}
-        iconLabel={Boolean(media['aria-hidden']) ? null : media['aria-label']}
+        iconLabel={media['aria-hidden'] ? null : media['aria-label']}
       />
     );
   };
@@ -148,9 +155,9 @@ export const ActionPrompt = ({
           </Button>
         </>
       }
-      onDismiss={onDismiss}
       role="region"
-      {...(Boolean(ariaLabel)
+      onDismiss={onDismiss}
+      {...(ariaLabel
         ? { 'aria-label': ariaLabel }
         : {
             'aria-labelledby': ariaLabelledByIds,
@@ -158,10 +165,14 @@ export const ActionPrompt = ({
           })}
     >
       <div className={clsx('d-flex', 'flex-column', 'justify-content-center')}>
-        <Body id={titleId} type={Typography.BODY_LARGE_BOLD}>
+        <Body id={titleId} type={Typography.BODY_LARGE_BOLD} className="wds-action-prompt__content">
           {title}
         </Body>
-        {description && <Body id={descId}>{description}</Body>}
+        {description && (
+          <Body id={descId} className="wds-action-prompt__content">
+            {description}
+          </Body>
+        )}
       </div>
     </PrimitivePrompt>
   );