@transferwise/components 0.0.0-experimental-1de8033 → 0.0.0-experimental-2b6c540

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 { Bank, Star, Travel, Briefcase } from '@transferwise/icons';
+import { ActionPrompt, type ActionPromptProps } from './ActionPrompt';
 import { lorem10 } from '../../test-utils';
-import Body from '../../body';
-import { action } from 'storybook/actions';
+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>;
 
 const withComponentGrid =
   ({ maxWidth = 'auto', gap = '1rem' } = {}) =>
@@ -37,151 +26,326 @@ 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' },
+      },
+    },
+  },
+  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,
+  },
+};
+
+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' } },
 };
 
-export const PrimaryActionOnly: Story = {
+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 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="warning"
-          title="Session expiring soon"
-          action={{ label: 'Stay logged in', onClick: fn() }}
-          actionSecondary={{ label: 'Log out', onClick: fn() }}
-          onDismiss={fn()}
-        />
-        <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()],
+      ))}
+    </>
+  ),
 };
 
-export const Media: Story = {
+/**
+ * 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() }}
+      />
+    </>
+  ),
+};
+
+/**
+ * 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',
+      },
+    },
+  },
+};

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,

package/src/prompt/InfoPrompt/InfoPrompt.accessibility.docs.mdx

@@ -0,0 +1,79 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Prompts/InfoPrompt/Accessibility" />
+
+# Accessibility
+
+Under the hood, `InfoPrompt` is marked as `role="region"` for a section of content that users might want to navigate to directly.
+
+By default, it's labelled by the `title` and described by the `description`.
+
+## Announcement Behaviour
+
+`InfoPrompt` is designed for contextual messages that appear within a screen. Unlike `ActionPrompt`, it can be configured to announce to screen readers using ARIA roles:
+
+- **`role="status"`**: Politely announces updates when the screen reader is idle. Use for non-critical success messages or informational updates (e.g., "Your profile has been saved").
+- **`role="alert"`**: Immediately interrupts to announce urgent messages. Use for time-sensitive information that requires immediate attention (e.g., errors, warnings, deadlines).
+
+**Default behavior:** Without a role, the prompt won't be announced automatically. Users will encounter it when navigating the page.
+
+<Source
+  dark
+  code={`
+// Polite announcement for non-critical updates
+<InfoPrompt
+  sentiment="success"
+  description="Your profile has been saved"
+  role="status"
+/>
+
+// Immediate announcement for urgent messages
+
+<InfoPrompt
+  sentiment="negative"
+  title="Session expired"
+  description="Your session has expired. Please log in again."
+  role="alert"
+/>
+`}
+/>
+
+## Custom Labels
+
+If you want to provide a custom label for screen readers, you can use the `aria-label` prop. Make sure to include all necessary information in it, because when provided, the default labelling will be removed.
+
+<Source
+  dark
+  code={`
+<InfoPrompt
+  sentiment="negative"
+  title="Payment failed"
+  description="Unable to process payment."
+  aria-label="Critical error: Your payment could not be processed. Please update your payment method and try again within 24 hours."
+/>
+`}
+/>
+
+## Media
+
+Custom media icons should include their own accessibility attributes. Use the `title` prop on icons to provide accessible names for screen readers:
+
+<Source
+  dark
+  code={`
+<InfoPrompt
+  sentiment="success"
+  description="Your travel account is ready!"
+  media={{ asset: <Travel title="Travel feature" /> }}
+/>
+
+<InfoPrompt
+  sentiment="warning"
+  title="Business travel"
+  description="Book your business trip with Wise."
+  media={{ asset: <Briefcase title="Business" /> }}
+/>
+`}
+/>
+
+**Note:** Unlike `ActionPrompt` (which uses `media['aria-label']`) and `InlinePrompt` (which uses `mediaLabel`), `InfoPrompt` requires you to add accessibility attributes directly to the icon component you pass.