@transferwise/components 46.115.1 → 46.116.1

package/src/sentimentSurface/SentimentSurface.story.tsx

@@ -0,0 +1,303 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import SentimentSurface from './SentimentSurface';
+import { storyConfig } from '../test-utils';
+import type { Sentiment, Emphasis } from './SentimentSurface.types';
+
+const withContainer = (Story: () => JSX.Element) => (
+  <div style={{ display: 'flex', justifyContent: 'center', padding: '2rem' }}>
+    <Story />
+  </div>
+);
+
+const withComponentGrid = (Story: () => JSX.Element) => (
+  <div
+    style={{
+      width: '100%',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: '1rem',
+      maxWidth: '800px',
+    }}
+  >
+    <Story />
+  </div>
+);
+
+/**
+ * SentimentSurface is a polymorphic container component that applies contextual background colours
+ * and text styling based on sentiment types.
+ */
+const meta: Meta<typeof SentimentSurface> = {
+  component: SentimentSurface,
+  title: 'Content/SentimentSurface',
+  argTypes: {
+    sentiment: {
+      control: 'select',
+      options: ['negative', 'warning', 'neutral', 'success', 'proposition'],
+      description: 'The sentiment type that determines the colour scheme',
+    },
+    emphasis: {
+      control: 'select',
+      options: ['base', 'elevated'],
+      description: 'The emphasis level affecting background and text contrast',
+      table: {
+        defaultValue: { summary: 'base' },
+      },
+    },
+    as: {
+      control: 'text',
+      description: 'The underlying HTML element to render',
+      table: {
+        defaultValue: { summary: 'div' },
+      },
+    },
+    children: {
+      control: 'text',
+      description: 'Content to render inside the surface',
+    },
+    className: {
+      control: 'text',
+      description: 'Additional CSS classes',
+    },
+    id: {
+      control: 'text',
+      description: 'Unique identifier for the component',
+    },
+    testId: {
+      control: 'text',
+      description: 'Test ID for React Testing Library',
+    },
+  },
+  args: {
+    sentiment: 'neutral',
+    emphasis: 'base',
+    children: 'This is a sentiment surface',
+  },
+  decorators: [withContainer],
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SentimentSurface>;
+
+/**
+ * The Playground story allows you to experiment with all the props of the SentimentSurface component.
+ * Use the controls below to customise the sentiment type, emphasis level, and content.
+ */
+export const Playground: Story = {
+  args: {
+    sentiment: 'negative',
+    emphasis: 'base',
+    children: (
+      <div
+        style={{
+          padding: '24px',
+          backgroundColor: 'var(--color-sentiment-background-surface)',
+          color: 'var(--color-sentiment-content-primary)',
+        }}
+      >
+        This is a custom div demostrating a sentiment surface.
+      </div>
+    ),
+  },
+};
+
+/**
+ * Each sentiment type has two emphasis levels – base and elevated – to provide different levels of visual prominence.
+ */
+export const EmphasisLevels: Story = {
+  render: (args) => (
+    <>
+      <SentimentSurface {...args} sentiment="negative" emphasis="base">
+        <div
+          style={{
+            padding: '24px',
+            backgroundColor: 'var(--color-sentiment-background-surface)',
+            color: 'var(--color-sentiment-content-primary)',
+          }}
+        >
+          Negative - Base emphasis
+        </div>
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="negative" emphasis="elevated">
+        <div
+          style={{
+            padding: '24px',
+            backgroundColor: 'var(--color-sentiment-background-surface)',
+            color: 'var(--color-sentiment-content-primary)',
+          }}
+        >
+          Negative - Elevated emphasis
+        </div>
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success" emphasis="base">
+        <div
+          style={{
+            padding: '24px',
+            backgroundColor: 'var(--color-sentiment-background-surface)',
+            color: 'var(--color-sentiment-content-primary)',
+          }}
+        >
+          Success - Base emphasis
+        </div>
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success" emphasis="elevated">
+        <div
+          style={{
+            padding: '24px',
+            backgroundColor: 'var(--color-sentiment-background-surface)',
+            color: 'var(--color-sentiment-content-primary)',
+          }}
+        >
+          Success - Elevated emphasis
+        </div>
+      </SentimentSurface>
+    </>
+  ),
+  parameters: {
+    controls: { disable: true },
+  },
+  decorators: [withComponentGrid],
+};
+
+const sentiments: Sentiment[] = ['negative', 'warning', 'neutral', 'success', 'proposition'];
+const emphasisLevels: Emphasis[] = ['base', 'elevated'];
+const tokenCategories = [
+  {
+    name: 'Content',
+    tokens: [
+      '--color-sentiment-content-primary',
+      '--color-sentiment-content-primary-hover',
+      '--color-sentiment-content-primary-active',
+    ],
+  },
+  {
+    name: 'Interactive Primary',
+    tokens: [
+      '--color-sentiment-interactive-primary',
+      '--color-sentiment-interactive-primary-hover',
+      '--color-sentiment-interactive-primary-active',
+    ],
+  },
+  {
+    name: 'Interactive Secondary',
+    tokens: [
+      '--color-sentiment-interactive-secondary',
+      '--color-sentiment-interactive-secondary-hover',
+      '--color-sentiment-interactive-secondary-active',
+    ],
+  },
+  {
+    name: 'Interactive Control',
+    tokens: [
+      '--color-sentiment-interactive-control',
+      '--color-sentiment-interactive-control-hover',
+      '--color-sentiment-interactive-control-active',
+    ],
+  },
+  {
+    name: 'Background Surface',
+    tokens: [
+      '--color-sentiment-background-surface',
+      '--color-sentiment-background-surface-hover',
+      '--color-sentiment-background-surface-active',
+    ],
+  },
+];
+
+const TokenSwatch = ({ token }: { token: string }) => (
+  <div style={{ display: 'flex', alignItems: 'center', gap: '12px', marginBottom: '4px' }}>
+    <div
+      style={{
+        width: '32px',
+        height: '32px',
+        borderRadius: '4px',
+        backgroundColor: `var(${token})`,
+        border: '1px solid rgba(0,0,0,0.1)',
+        flexShrink: 0,
+      }}
+    />
+    <code style={{ fontSize: '12px', color: 'var(--color-sentiment-content-primary)' }}>
+      {token}
+    </code>
+  </div>
+);
+
+/**
+ * Visual demonstration of the CSS custom properties (tokens) set by each sentiment and emphasis combination.
+ * These tokens enable child components to automatically adapt their styling to the sentiment context.
+ */
+export const Tokens: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '32px', maxWidth: '100%' }}>
+      {sentiments.map((sentiment) =>
+        emphasisLevels.map((emphasis) => (
+          <SentimentSurface
+            key={`${sentiment}-${emphasis}`}
+            sentiment={sentiment}
+            emphasis={emphasis}
+            style={{
+              padding: '24px',
+              borderRadius: '16px',
+              backgroundColor: 'var(--color-sentiment-background-surface)',
+              color: 'var(--color-sentiment-content-primary)',
+            }}
+          >
+            <div style={{ marginBottom: '16px' }}>
+              <strong
+                style={{
+                  fontSize: '16px',
+                  textTransform: 'capitalize',
+                }}
+              >
+                {sentiment} - {emphasis}
+              </strong>
+            </div>
+            <div
+              style={{
+                display: 'grid',
+                gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
+                gap: '24px',
+              }}
+            >
+              {tokenCategories.map((category) => (
+                <div key={category.name}>
+                  <div
+                    style={{
+                      fontSize: '12px',
+                      fontWeight: 600,
+                      marginBottom: '8px',
+                      textTransform: 'uppercase',
+                      letterSpacing: '0.5px',
+                      opacity: 0.7,
+                    }}
+                  >
+                    {category.name}
+                  </div>
+                  {category.tokens.map((token) => (
+                    <TokenSwatch key={token} token={token} />
+                  ))}
+                </div>
+              ))}
+            </div>
+          </SentimentSurface>
+        )),
+      )}
+    </div>
+  ),
+  parameters: {
+    controls: { disable: true },
+  },
+  decorators: [
+    (Story: () => JSX.Element) => (
+      <div style={{ padding: '2rem', maxWidth: '1200px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/sentimentSurface/SentimentSurface.tests.story.tsx

@@ -0,0 +1,72 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import SentimentSurface from './SentimentSurface';
+
+export default {
+  component: SentimentSurface,
+  title: 'Content/SentimentSurface/Tests',
+} satisfies Meta<typeof SentimentSurface>;
+
+type Story = StoryObj<typeof SentimentSurface>;
+
+export const NestedSentiments: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
+      <SentimentSurface
+        sentiment="negative"
+        emphasis="base"
+        style={{
+          backgroundColor: 'var(--color-sentiment-background-surface)',
+          color: 'var(--color-sentiment-content-primary)',
+        }}
+      >
+        Outer: Negative, base
+        <div style={{ margin: '16px 0 0 16px' }}>
+          <SentimentSurface
+            sentiment="success"
+            emphasis="elevated"
+            style={{
+              backgroundColor: 'var(--color-sentiment-background-surface)',
+              color: 'var(--color-sentiment-content-primary)',
+            }}
+          >
+            Inner: Success, elevated
+            <div style={{ margin: '12px 0 0 12px' }}>
+              <SentimentSurface
+                sentiment="warning"
+                emphasis="base"
+                style={{
+                  backgroundColor: 'var(--color-sentiment-background-surface)',
+                  color: 'var(--color-sentiment-content-primary)',
+                }}
+              >
+                Deepest: Warning, base
+              </SentimentSurface>
+            </div>
+          </SentimentSurface>
+        </div>
+      </SentimentSurface>
+      <SentimentSurface
+        sentiment="proposition"
+        emphasis="elevated"
+        style={{
+          backgroundColor: 'var(--color-sentiment-background-surface)',
+          color: 'var(--color-sentiment-content-primary)',
+        }}
+      >
+        Outer: Proposition, elevated
+        <div style={{ margin: '16px 0 0 16px' }}>
+          <SentimentSurface
+            sentiment="neutral"
+            emphasis="base"
+            style={{
+              backgroundColor: 'var(--color-sentiment-background-surface)',
+              color: 'var(--color-sentiment-content-primary)',
+            }}
+          >
+            Inner: Neutral, base
+          </SentimentSurface>
+        </div>
+      </SentimentSurface>
+    </div>
+  ),
+};

package/src/sentimentSurface/SentimentSurface.tsx

@@ -0,0 +1,72 @@
+import { forwardRef, ElementType, ForwardedRef } from 'react';
+import { clsx } from 'clsx';
+
+import {
+  SentimentSurfaceComponentProps,
+  SentimentSurfaceComponent,
+} from './SentimentSurface.types';
+import { getSentimentSurfaceClassName } from './classMap';
+
+/**
+ * SentimentSurface is a polymorphic container component that applies contextual background colours
+ * and text styling based on sentiment types (negative, warning, neutral, success, proposition).
+ * It's designed to visually communicate the nature or importance of its content through colour.
+ *
+ * @param {ElementType} [as='div'] - Optional prop to override the HTML element rendered.
+ * @param {Sentiment} sentiment - Required prop to set the sentiment type (negative, warning, neutral, success, proposition).
+ * @param {Emphasis} [emphasis='base'] - Optional prop to specify the emphasis level (base or elevated).
+ * @param {ReactNode} [children] - Content to render inside the surface.
+ * @param {string} [className] - Additional CSS classes to apply.
+ * @param {CSSProperties} [style] - Inline styles to apply.
+ * @param {string} [id] - Unique identifier for the component.
+ * @param {string} [testId] - A unique string that appears as data attribute `data-testid` in the rendered code.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic usage with negative sentiment
+ * <SentimentSurface sentiment="negative">
+ *   Your payment has failed
+ * </SentimentSurface>
+ * ```
+ *
+ * @see {@link SentimentSurface} for further information.
+ * @see {@link https://storybook.wise.design/?path=/docs/sentiment-surface--docs|Storybook Wise Design}
+ */
+// @ts-expect-error - Generic forwardRef limitation. See: https://fettblog.eu/typescript-react-generic-forward-refs/
+const SentimentSurface: SentimentSurfaceComponent = forwardRef(function SentimentSurface<
+  T extends ElementType = 'div',
+>(
+  {
+    as,
+    sentiment,
+    emphasis = 'base',
+    className,
+    style,
+    children,
+    id,
+    testId,
+    ...props
+  }: SentimentSurfaceComponentProps<T>,
+  ref: ForwardedRef<HTMLElement>,
+) {
+  const Element = as ?? 'div';
+  const classNames = clsx(getSentimentSurfaceClassName(sentiment, emphasis), className);
+  const sentimentProps = {
+    ref,
+    id,
+    'data-testid': testId,
+    className: classNames,
+    style,
+    ...props,
+  };
+
+  return (
+    // @ts-expect-error - Generic forwardRef limitation. See: https://fettblog.eu/typescript-react-generic-forward-refs/
+    <Element {...sentimentProps}>{children}</Element>
+  );
+});
+
+SentimentSurface.displayName = 'SentimentSurface';
+
+export default SentimentSurface;

package/src/sentimentSurface/SentimentSurface.types.ts

@@ -0,0 +1,104 @@
+import {
+  ReactNode,
+  ElementType,
+  CSSProperties,
+  ComponentPropsWithoutRef,
+  HTMLAttributes,
+} from 'react';
+
+/**
+ * Sentiment types for the SentimentSurface component
+ */
+export type Sentiment = 'negative' | 'warning' | 'neutral' | 'success' | 'proposition';
+
+/**
+ * Emphasis levels for the SentimentSurface component
+ */
+export type Emphasis = 'base' | 'elevated';
+
+/**
+ * Common properties for the SentimentSurface component
+ */
+export interface CommonProps {
+  /**
+   * The sentiment type that determines the colour scheme
+   */
+  sentiment: Sentiment;
+
+  /**
+   * The emphasis level affecting background and text contrast
+   * @default 'base'
+   */
+  emphasis?: Emphasis;
+
+  /**
+   * Content to render inside the surface
+   */
+  children?: ReactNode;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Inline styles
+   */
+  style?: CSSProperties;
+
+  /**
+   * Unique identifier for the component
+   */
+  id?: string;
+
+  /**
+   * A unique string that appears as data attribute `data-testid` in the rendered code, serving as a hook for automated tests
+   */
+  testId?: string;
+
+  /**
+   * `data-testid` is strictly controlled through the `testId` prop.
+   * This lets consumers know that this data attribute will not be applied.
+   */
+  'data-testid'?: never;
+}
+
+/**
+ * Props when rendering as a div or custom element
+ */
+export type SentimentSurfaceDivProps<T extends ElementType = 'div'> = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  keyof CommonProps
+> &
+  CommonProps & {
+    /**
+     * The underlying HTML element to render
+     * @default 'div'
+     */
+    as?: T;
+  };
+
+/**
+ * All possible props for the SentimentSurface component
+ */
+export type SentimentSurfaceProps<T extends ElementType = 'div'> = SentimentSurfaceDivProps<T>;
+
+/**
+ * Combines SentimentSurface props with all valid HTML attributes for the specified element type.
+ * Supports polymorphic rendering via the `as` prop while maintaining full type safety.
+ *
+ * @example
+ * <SentimentSurface sentiment="negative" role="alert" aria-live="polite">
+ *   Error message
+ * </SentimentSurface>
+ */
+export type SentimentSurfaceComponentProps<T extends ElementType = 'div'> =
+  SentimentSurfaceProps<T> & Omit<ComponentPropsWithoutRef<T>, keyof SentimentSurfaceProps<T>>;
+
+/**
+ * The SentimentSurface component type signature
+ */
+export interface SentimentSurfaceComponent {
+  <T extends ElementType = 'div'>(props: SentimentSurfaceComponentProps<T>): ReactNode;
+  displayName?: string;
+}

package/src/sentimentSurface/classMap.ts

@@ -0,0 +1,15 @@
+import type { Sentiment, Emphasis } from './SentimentSurface.types';
+
+const BASE_CLASS = 'wds-sentiment-surface';
+
+export const sentimentClassMap: Record<Sentiment, string> = {
+  negative: `${BASE_CLASS}-negative`,
+  warning: `${BASE_CLASS}-warning`,
+  neutral: `${BASE_CLASS}-neutral`,
+  success: `${BASE_CLASS}-success`,
+  proposition: `${BASE_CLASS}-proposition`,
+};
+
+export const getSentimentSurfaceClassName = (sentiment: Sentiment, emphasis: Emphasis): string => {
+  return `${BASE_CLASS} ${sentimentClassMap[sentiment]}-${emphasis}`;
+};

package/src/sentimentSurface/index.ts

@@ -0,0 +1,8 @@
+export { default } from './SentimentSurface';
+export type {
+  SentimentSurfaceComponent,
+  SentimentSurfaceProps,
+  CommonProps,
+  Sentiment,
+  Emphasis,
+} from './SentimentSurface.types';

package/src/statusIcon/StatusIcon.css

@@ -1,38 +1,6 @@
-.status-circle .light {
-  color: var(--color-contrast-overlay);
+.wds-sentiment-surface.status-circle {
+  background-color: var(--color-sentiment-interactive-primary);
 }
-.np-theme-personal--bright-green .status-circle .light {
-  color: var(--color-white);
-}
-.status-circle .dark {
-  color: #37517e;
-  color: var(--color-content-primary);
-}
-.status-circle.warning,
-.status-circle.pending {
-  background-color: var(--color-sentiment-warning);
-}
-.np-theme-personal .status-circle.warning .status-icon,
-.np-theme-personal .status-circle.pending .status-icon {
-  color: var(--color-dark);
-}
-.status-circle.negative,
-.status-circle.error {
-  background-color: var(--color-sentiment-negative);
-}
-.status-circle.negative .status-icon,
-.status-circle.error .status-icon {
-  color: var(--color-sentiment-negative-secondary);
-}
-.status-circle.neutral {
-  background-color: #5d7079;
-  background-color: var(--color-content-secondary);
-}
-.status-circle.positive,
-.status-circle.success {
-  background-color: var(--color-sentiment-positive);
-}
-.status-circle.positive .status-icon,
-.status-circle.success .status-icon {
-  color: var(--color-sentiment-positive-secondary);
+.wds-sentiment-surface.status-circle .status-icon {
+  color: var(--color-sentiment-interactive-control);
 }

package/src/statusIcon/StatusIcon.less

@@ -1,44 +1,6 @@
-.status-circle {
-  .light {
-    color: var(--color-contrast-overlay);
-
-    .np-theme-personal--bright-green & {
-      color: var(--color-white);
-    }
-  }
-
-  .dark {
-    color: var(--color-content-primary);
-  }
-
-  &.warning,
-  &.pending {
-    background-color: var(--color-sentiment-warning);
-
-    .status-icon {
-      .np-theme-personal & {
-        color: var(--color-dark);
-      }
-    }
-  }
-}
-
-.status-circle.negative,
-.status-circle.error {
-  background-color: var(--color-sentiment-negative);
-  .status-icon {
-    color: var(--color-sentiment-negative-secondary);
-  }
-}
-
-.status-circle.neutral {
-  background-color: var(--color-content-secondary);
-}
-
-.status-circle.positive,
-.status-circle.success {
-  background-color: var(--color-sentiment-positive);
+.wds-sentiment-surface.status-circle {
+  background-color: var(--color-sentiment-interactive-primary);
   .status-icon {
-    color: var(--color-sentiment-positive-secondary);
+    color: var(--color-sentiment-interactive-control);
   }
 }

package/src/statusIcon/StatusIcon.tsx

@@ -1,7 +1,9 @@
 import { Info, Alert, Cross, Check, ClockBorderless } from '@transferwise/icons';
 import { clsx } from 'clsx';
 import { useIntl } from 'react-intl';
+import { PropsWithChildren } from 'react';
 
+import SentimentSurface from '../sentimentSurface';
 import { SizeSmall, SizeMedium, SizeLarge, Sentiment, Size, Breakpoint, Status } from '../common';
 import Circle, { CircleProps } from '../common/circle';
 import { useMedia } from '../common/hooks/useMedia';
@@ -81,9 +83,20 @@ const StatusIcon = ({ sentiment = 'neutral', size: sizeProp = 40, iconLabel }: S
   const iconColor = sentiment === 'warning' || sentiment === 'pending' ? 'dark' : 'light';
   const isTinyViewport = useMedia(`(max-width: ${Breakpoint.ZOOM_400}px)`);
   const size = mapLegacySize[sizeProp] ?? sizeProp;
+  // eslint-disable-next-line react/no-unstable-nested-components
+  const SentimentSurfaceSetting = (props: PropsWithChildren<Pick<CircleProps, 'className'>>) => (
+    <SentimentSurface
+      as="span"
+      // @ts-expect-error sentiment and SentimentSurface types mismatch
+      sentiment={
+        sentiment === 'positive' ? 'success' : sentiment === 'pending' ? 'warning' : sentiment
+      }
+      {...props}
+    />
+  );
   return (
     <Circle
-      as="span"
+      as={SentimentSurfaceSetting}
       size={isTinyViewport && size < 40 ? 32 : size}
       data-testid="status-icon"
       className={clsx('status-circle', sentiment)}