@transferwise/components 0.0.0-experimental-b6b6dc1 → 0.0.0-experimental-a308934

package/src/prompt/CriticalBanner/CriticalBanner.tsx

@@ -0,0 +1,188 @@
+import { AriaAttributes, ReactNode, useId } from 'react';
+import { clsx } from 'clsx';
+
+import Body from '../../body';
+import Button from '../../button';
+import { Breakpoint, LiveRegion, Typography } from '../../common';
+import { ButtonProps } from '../../button/Button.types';
+import { PrimitivePrompt, PrimitivePromptProps } from '../PrimitivePrompt';
+import { useScreenSize } from '../../common/hooks/useScreenSize';
+
+import { renderPromptMedia, PromptMedia } from '../helpers/promptMedia';
+import { shouldShowWhenExpanded, ExpanderToggle } from '../common/Expander/Expander';
+import { buildAnnouncementString } from './helpers';
+
+export type CriticalBannerProps = {
+  title?: ReactNode;
+  description?: ReactNode;
+  /** @default {} */
+  media?: PromptMedia;
+  action?: Pick<ButtonProps, 'onClick' | 'href' | 'target'> & {
+    label: ButtonProps['children'];
+  };
+  actionSecondary?: Pick<ButtonProps, 'onClick' | 'href' | 'target'> & {
+    label: ButtonProps['children'];
+  };
+  /**
+   * The sentiment determines the colour scheme
+   * @default 'negative'
+   */
+  sentiment?: Exclude<PrimitivePromptProps['sentiment'], 'proposition'>;
+  /**
+   * Whether the banner is expanded (showing description and actions)
+   */
+  expanded: boolean;
+  /**
+   * Callback when the chevron toggle is clicked
+   */
+  onToggle: () => void;
+  'aria-label'?: AriaAttributes['aria-label'];
+} & Pick<PrimitivePromptProps, 'id' | 'className' | 'data-testid'>;
+
+/**
+ * CriticalBanner is a full-width banner component for critical messages that require attention.
+ * It features a collapsible design with a chevron toggle to show/hide description and action buttons.
+ * Unlike ActionPrompt, it has no dismiss button and no border radius.
+ *
+ * The component is fully controlled - parent owns the `expanded` state and provides `onToggle` callback.
+ *
+ * **Accessibility:** Uses `aria-live="assertive"` to immediately announce critical messages to screen readers.
+ * See the Accessibility documentation for detailed information on announcement behavior and testing.
+ */
+export const CriticalBanner = ({
+  sentiment = 'negative',
+  title,
+  description,
+  media = {},
+  action,
+  actionSecondary,
+  expanded,
+  onToggle,
+  id,
+  className,
+  'data-testid': testId,
+  'aria-label': ariaLabel,
+}: CriticalBannerProps) => {
+  const isMobile = !useScreenSize(Breakpoint.MEDIUM);
+  const mediaId = useId();
+  const titleId = useId();
+  const descId = useId();
+
+  const ariaLabelledByIds = [
+    media['aria-hidden'] ? undefined : mediaId,
+    ariaLabel || !title ? undefined : titleId,
+  ]
+    .filter(Boolean)
+    .join(' ');
+  const hasActions = action || actionSecondary;
+
+  return (
+    <LiveRegion
+      aria-live="assertive"
+      announceOnChange={buildAnnouncementString({
+        title,
+        description,
+        expanded,
+        actionLabel: action?.label,
+        actionSecondaryLabel: actionSecondary?.label,
+      })}
+    >
+      <PrimitivePrompt
+        id={id}
+        sentiment={sentiment}
+        emphasis={sentiment === 'neutral' ? 'base' : 'elevated'}
+        data-testid={testId}
+        className={clsx(
+          'wds-critical-banner',
+          {
+            'wds-critical-banner--collapsed': !expanded,
+            'wds-critical-banner--with-two-actions': !!actionSecondary,
+          },
+          className,
+        )}
+        media={renderPromptMedia({
+          media,
+          sentiment,
+          mediaId,
+          imgClassName: 'wds-critical-banner--media-image',
+        })}
+        actions={
+          shouldShowWhenExpanded({ expanded, hasContent: !!hasActions }) ? (
+            <>
+              {actionSecondary && (
+                // @ts-expect-error onClick type mismatch
+                <Button
+                  v2
+                  size="md"
+                  priority="secondary"
+                  href={actionSecondary.href}
+                  block={isMobile}
+                  onClick={actionSecondary?.onClick}
+                >
+                  {actionSecondary.label}
+                </Button>
+              )}
+              {action && (
+                // @ts-expect-error onClick type mismatch
+                <Button
+                  v2
+                  size="md"
+                  priority="primary"
+                  href={action.href}
+                  block={isMobile}
+                  onClick={action.onClick}
+                >
+                  {action.label}
+                </Button>
+              )}
+            </>
+          ) : undefined
+        }
+        role="region"
+        {...(ariaLabel
+          ? { 'aria-label': ariaLabel }
+          : {
+              'aria-labelledby': ariaLabelledByIds,
+              'aria-describedby': descId,
+            })}
+      >
+        <div
+          className={clsx(
+            'd-flex',
+            'flex-column',
+            'justify-content-center',
+            'wds-critical-banner__text-wrapper',
+          )}
+        >
+          {title && (
+            <Body
+              id={titleId}
+              type={Typography.BODY_LARGE_BOLD}
+              className="wds-critical-banner__content"
+            >
+              {title}
+            </Body>
+          )}
+          {shouldShowWhenExpanded({ expanded, hasContent: !!description, alwaysShow: !title }) && (
+            <Body
+              id={descId}
+              className={clsx('wds-critical-banner__content', {
+                'wds-critical-banner__description--collapsed': !expanded && !title,
+              })}
+            >
+              {description}
+            </Body>
+          )}
+        </div>
+        <ExpanderToggle
+          expanded={expanded}
+          size={24}
+          className="wds-critical-banner__toggle"
+          onToggle={onToggle}
+        />
+      </PrimitivePrompt>
+    </LiveRegion>
+  );
+};
+
+export default CriticalBanner;

package/src/prompt/CriticalBanner/helpers.ts

@@ -0,0 +1,39 @@
+import { ReactNode } from 'react';
+
+/**
+ * Helper to extract string from ReactNode for announcements.
+ * Complex ReactNodes (JSX elements) return empty string.
+ */
+export const getStringValue = (node: ReactNode): string => {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node);
+  }
+  return '';
+};
+
+/**
+ * Builds the announcement string from visible content only.
+ * Content visibility depends on expanded state and presence of title.
+ */
+export const buildAnnouncementString = ({
+  title,
+  description,
+  expanded,
+  actionLabel,
+  actionSecondaryLabel,
+}: {
+  title?: ReactNode;
+  description?: ReactNode;
+  expanded: boolean;
+  actionLabel?: ReactNode;
+  actionSecondaryLabel?: ReactNode;
+}): string => {
+  return [
+    title ? getStringValue(title) : undefined,
+    description && (expanded || !title) ? getStringValue(description) : undefined,
+    expanded && actionLabel ? getStringValue(actionLabel) : undefined,
+    expanded && actionSecondaryLabel ? getStringValue(actionSecondaryLabel) : undefined,
+  ]
+    .filter(Boolean)
+    .join('|');
+};

package/src/prompt/CriticalBanner/index.ts

@@ -0,0 +1,2 @@
+export type { CriticalBannerProps } from './CriticalBanner';
+export { CriticalBanner } from './CriticalBanner';

package/src/prompt/PrimitivePrompt/PrimitivePrompt.tsx

@@ -1,6 +1,6 @@
 import { Cross } from '@transferwise/icons';
 import { clsx } from 'clsx';
-import SentimentSurface, { Sentiment } from '../../sentimentSurface';
+import SentimentSurface, { Emphasis, Sentiment } from '../../sentimentSurface';
 import IconButton from '../../iconButton';
 import { useIntl } from 'react-intl';
 import closeBtnMessages from '../../common/closeButton/CloseButton.messages';
@@ -8,10 +8,15 @@ import { HTMLAttributes, ReactNode } from 'react';
 
 export type PrimitivePromptProps = HTMLAttributes<HTMLDivElement> & {
   /**
-   * The sentiment determines the colour scheme
+   * The sentiment determines the colour scheme.
    * @default success
    */
   sentiment?: Sentiment;
+  /**
+   * The emphasis level affecting background and text contrast.
+   * @default 'base
+   */
+  emphasis?: Emphasis;
   /**
    * Media to be displayed on the prompt (icon/image/etc).
    */
@@ -35,6 +40,7 @@ export type PrimitivePromptProps = HTMLAttributes<HTMLDivElement> & {
  * Uses several css variables to handle styling from within the consuming component, e.g. --Prompt-padding. */
 export const PrimitivePrompt = ({
   sentiment = 'success',
+  emphasis = 'base',
   media,
   actions,
   onDismiss,
@@ -47,6 +53,7 @@ export const PrimitivePrompt = ({
   return (
     <SentimentSurface
       sentiment={sentiment}
+      emphasis={emphasis}
       className={clsx('wds-prompt', `wds-prompt--${sentiment}`, className)}
       {...restProps}
     >

package/src/prompt/common/Expander/Expander.css

@@ -0,0 +1,8 @@
+.wds-expander-toggle {
+  align-self: flex-start;
+  flex-shrink: 0;
+  transition: transform 0.2s ease-in-out;
+}
+.wds-expander-toggle--collapsed {
+  transform: rotate(180deg);
+}

package/src/prompt/common/Expander/Expander.less

@@ -0,0 +1,9 @@
+.wds-expander-toggle {
+  align-self: flex-start;
+  flex-shrink: 0;
+  transition: transform 0.2s ease-in-out;
+
+  &--collapsed {
+    transform: rotate(180deg);
+  }
+}

package/src/prompt/common/Expander/Expander.messages.ts

@@ -0,0 +1,14 @@
+import { defineMessages } from 'react-intl';
+
+export default defineMessages({
+  expandAriaLabel: {
+    id: 'neptune.Expander.expandAriaLabel',
+    defaultMessage: 'Expand',
+    description: 'Expand button for expander',
+  },
+  collapseAriaLabel: {
+    id: 'neptune.Expander.collapseAriaLabel',
+    defaultMessage: 'Collapse',
+    description: 'Collapse button for expander',
+  },
+});

package/src/prompt/common/Expander/Expander.test.tsx

@@ -0,0 +1,167 @@
+import { renderHook, act, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { useExpanderState, shouldShowWhenExpanded, ExpanderToggle } from './Expander';
+import { mockMatchMedia, render } from '../../../test-utils';
+
+mockMatchMedia();
+
+describe('useExpanderState', () => {
+  it('initializes with default expanded state (true)', () => {
+    const { result } = renderHook(() => useExpanderState());
+
+    expect(result.current.expanded).toBe(true);
+  });
+
+  it('initializes with custom expanded state', () => {
+    const { result } = renderHook(() => useExpanderState(false));
+
+    expect(result.current.expanded).toBe(false);
+  });
+
+  it('toggles expanded state', () => {
+    const { result } = renderHook(() => useExpanderState(true));
+
+    expect(result.current.expanded).toBe(true);
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.expanded).toBe(false);
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.expanded).toBe(true);
+  });
+
+  it('sets expanded state programmatically', () => {
+    const { result } = renderHook(() => useExpanderState(true));
+
+    act(() => {
+      result.current.setExpanded(false);
+    });
+
+    expect(result.current.expanded).toBe(false);
+
+    act(() => {
+      result.current.setExpanded(true);
+    });
+
+    expect(result.current.expanded).toBe(true);
+  });
+
+  it('memoizes toggle callback', () => {
+    const { result, rerender } = renderHook(() => useExpanderState(true));
+
+    const firstToggle = result.current.toggle;
+
+    rerender();
+
+    expect(result.current.toggle).toBe(firstToggle);
+  });
+});
+
+describe('shouldShowWhenExpanded', () => {
+  it('returns false when hasContent is false', () => {
+    expect(shouldShowWhenExpanded({ expanded: true, hasContent: false })).toBe(false);
+    expect(shouldShowWhenExpanded({ expanded: false, hasContent: false })).toBe(false);
+  });
+
+  it('returns true when expanded and hasContent are true', () => {
+    expect(shouldShowWhenExpanded({ expanded: true, hasContent: true })).toBe(true);
+  });
+
+  it('returns false when collapsed but hasContent is true', () => {
+    expect(shouldShowWhenExpanded({ expanded: false, hasContent: true })).toBe(false);
+  });
+
+  it('returns true when alwaysShow is true and hasContent is true, regardless of expanded', () => {
+    expect(shouldShowWhenExpanded({ expanded: true, hasContent: true, alwaysShow: true })).toBe(
+      true,
+    );
+    expect(shouldShowWhenExpanded({ expanded: false, hasContent: true, alwaysShow: true })).toBe(
+      true,
+    );
+  });
+
+  it('returns false when alwaysShow is true but hasContent is false', () => {
+    expect(shouldShowWhenExpanded({ expanded: true, hasContent: false, alwaysShow: true })).toBe(
+      false,
+    );
+    expect(shouldShowWhenExpanded({ expanded: false, hasContent: false, alwaysShow: true })).toBe(
+      false,
+    );
+  });
+});
+
+describe('ExpanderToggle', () => {
+  it('renders with correct aria-label when expanded', () => {
+    render(<ExpanderToggle expanded onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveAttribute('aria-label', 'Collapse');
+  });
+
+  it('renders with correct aria-label when collapsed', () => {
+    render(<ExpanderToggle expanded={false} onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveAttribute('aria-label', 'Expand');
+  });
+
+  it('renders with custom labels', () => {
+    const { rerender } = render(<ExpanderToggle expanded onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveAttribute('aria-label', 'Collapse');
+
+    rerender(<ExpanderToggle expanded={false} onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveAttribute('aria-label', 'Expand');
+  });
+
+  it('sets aria-expanded attribute correctly', () => {
+    const { rerender } = render(<ExpanderToggle expanded onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'true');
+
+    rerender(<ExpanderToggle expanded={false} onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('calls onToggle when clicked', async () => {
+    const user = userEvent.setup();
+    const onToggle = jest.fn();
+
+    render(<ExpanderToggle expanded onToggle={onToggle} />);
+
+    await user.click(screen.getByRole('button'));
+
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('applies custom className', () => {
+    render(<ExpanderToggle expanded className="custom-class" onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveClass('custom-class');
+  });
+
+  it('applies base class and collapsed class correctly', () => {
+    const { rerender } = render(<ExpanderToggle expanded onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveClass('wds-expander-toggle');
+    expect(screen.getByRole('button')).not.toHaveClass('wds-expander-toggle--collapsed');
+
+    rerender(<ExpanderToggle expanded={false} onToggle={jest.fn()} />);
+
+    expect(screen.getByRole('button')).toHaveClass('wds-expander-toggle');
+    expect(screen.getByRole('button')).toHaveClass('wds-expander-toggle--collapsed');
+  });
+
+  it('applies data-testid attribute', () => {
+    render(<ExpanderToggle expanded data-testid="expander-toggle" onToggle={jest.fn()} />);
+
+    expect(screen.getByTestId('expander-toggle')).toBeInTheDocument();
+  });
+});

package/src/prompt/common/Expander/Expander.tsx

@@ -0,0 +1,83 @@
+import { useState, useCallback } from 'react';
+import { clsx } from 'clsx';
+import { ChevronUp } from '@transferwise/icons';
+import IconButton from '../../../iconButton';
+import { useIntl } from 'react-intl';
+import messages from './Expander.messages';
+
+export type ExpanderState = {
+  expanded: boolean;
+  toggle: () => void;
+  setExpanded: (expanded: boolean) => void;
+};
+
+// Hook for managing expander state
+export function useExpanderState(initialExpanded = true): ExpanderState {
+  const [expanded, setExpanded] = useState(initialExpanded);
+
+  const toggle = useCallback(() => {
+    setExpanded((prev) => !prev);
+  }, []);
+
+  return {
+    expanded,
+    toggle,
+    setExpanded,
+  };
+}
+
+// Helper for conditional rendering based on expanded state
+export function shouldShowWhenExpanded({
+  expanded,
+  hasContent,
+  alwaysShow = false,
+}: {
+  expanded: boolean;
+  hasContent: boolean;
+  alwaysShow?: boolean;
+}): boolean {
+  if (alwaysShow) {
+    return hasContent;
+  }
+
+  return expanded && hasContent;
+}
+
+export type ExpanderToggleProps = {
+  expanded: boolean;
+  onToggle: () => void;
+  size?: 16 | 24 | 32 | 40 | 48 | 56 | 72;
+  className?: string;
+  'data-testid'?: string;
+};
+
+// Reusable toggle button component
+export const ExpanderToggle = ({
+  expanded,
+  onToggle,
+  size = 24,
+  className,
+  'data-testid': testId,
+}: ExpanderToggleProps) => {
+  const intl = useIntl();
+
+  return (
+    <IconButton
+      size={size}
+      priority="secondary"
+      aria-label={intl.formatMessage(
+        expanded ? messages.collapseAriaLabel : messages.expandAriaLabel,
+      )}
+      aria-expanded={expanded}
+      className={clsx(
+        'wds-expander-toggle',
+        { 'wds-expander-toggle--collapsed': !expanded },
+        className,
+      )}
+      data-testid={testId}
+      onClick={onToggle}
+    >
+      <ChevronUp />
+    </IconButton>
+  );
+};

package/src/prompt/helpers/promptMedia.tsx

@@ -0,0 +1,79 @@
+import { ReactNode } from 'react';
+import { GiftBox } from '@transferwise/icons';
+
+import AvatarView, { AvatarViewProps } from '../../avatarView';
+import Image from '../../image';
+import StatusIcon from '../../statusIcon';
+import { BadgeAssetsProps } from '../../badge';
+import { PrimitivePromptProps } from '../PrimitivePrompt';
+
+export type PromptMedia = {
+  imgSrc?: string;
+  avatar?: Pick<AvatarViewProps, 'imgSrc' | 'profileName' | 'profileType'> & {
+    asset?: AvatarViewProps['children'];
+    badge?: Pick<BadgeAssetsProps, 'flagCode'>;
+  };
+  'aria-label'?: string;
+  'aria-hidden'?: boolean;
+};
+
+type RenderPromptMediaOptions = {
+  media: PromptMedia;
+  sentiment: PrimitivePromptProps['sentiment'];
+  mediaId: string;
+  imgClassName: string;
+};
+
+export function renderPromptMedia({
+  media,
+  sentiment,
+  mediaId,
+  imgClassName,
+}: RenderPromptMediaOptions): ReactNode {
+  if (media?.imgSrc) {
+    return (
+      <Image
+        id={mediaId}
+        src={media.imgSrc}
+        className={imgClassName}
+        alt={media['aria-label'] ?? ''}
+      />
+    );
+  }
+  if (media?.avatar) {
+    const badge = media.avatar.badge
+      ? media.avatar.badge
+      : sentiment === 'proposition'
+        ? {}
+        : { status: sentiment };
+    return (
+      <AvatarView
+        {...media.avatar}
+        badge={badge}
+        aria-label={media['aria-label']}
+        aria-hidden={media['aria-hidden']}
+        id={mediaId}
+        size={48}
+      >
+        {media.avatar.asset}
+      </AvatarView>
+    );
+  }
+  return sentiment === 'proposition' ? (
+    <AvatarView
+      id={mediaId}
+      size={48}
+      aria-label={media['aria-label']}
+      aria-hidden={media['aria-hidden']}
+    >
+      <GiftBox />
+    </AvatarView>
+  ) : (
+    <StatusIcon
+      id={mediaId}
+      size={48}
+      sentiment={sentiment}
+      iconLabel={media['aria-hidden'] ? null : media['aria-label']}
+    />
+  );
+}

package/src/prompt/index.ts

@@ -12,3 +12,7 @@ export { ActionPrompt } from './ActionPrompt';
 // InfoPrompt
 export type { InfoPromptProps, InfoPromptAction, InfoPromptMedia } from './InfoPrompt';
 export { InfoPrompt } from './InfoPrompt';
+
+// CriticalBanner
+export type { CriticalBannerProps } from './CriticalBanner';
+export { CriticalBanner } from './CriticalBanner';