@transferwise/components 46.115.0 → 46.116.0

package/src/sentimentSurface/SentimentSurface.story.tsx

@@ -0,0 +1,340 @@
+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',
+    style: { padding: '24px', borderRadius: '16px' },
+  },
+  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: 'Customise the sentiment and emphasis using the controls below',
+  },
+};
+
+/**
+ * There are five different sentiment types that communicate different types of information or states.
+ */
+export const Sentiments: Story = {
+  render: (args) => (
+    <>
+      <SentimentSurface {...args} sentiment="negative">
+        Negative: Your payment has failed
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="warning">
+        Warning: Action required on your account
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="neutral">
+        Neutral: Your account is up to date
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success">
+        Success: Your payment was successful
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="proposition">
+        Proposition: Try our new feature
+      </SentimentSurface>
+    </>
+  ),
+  parameters: {
+    controls: { disable: true },
+  },
+  decorators: [withComponentGrid],
+};
+
+/**
+ * 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">
+        Negative - Base emphasis
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="negative" emphasis="elevated">
+        Negative - Elevated emphasis
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success" emphasis="base">
+        Success - Base emphasis
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success" emphasis="elevated">
+        Success - Elevated emphasis
+      </SentimentSurface>
+    </>
+  ),
+  parameters: {
+    controls: { disable: true },
+  },
+  decorators: [withComponentGrid],
+};
+
+/**
+ * The component can be rendered as any HTML element using the `as` prop.
+ */
+export const PolymorphicRendering: Story = {
+  render: (args) => (
+    <>
+      <SentimentSurface {...args} sentiment="negative">
+        Rendered as div (default)
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="negative" as="section">
+        Rendered as section
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="negative" as="article">
+        Rendered as article
+      </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' }}
+          >
+            <div style={{ marginBottom: '16px' }}>
+              <strong
+                style={{
+                  fontSize: '16px',
+                  textTransform: 'capitalize',
+                  color: 'var(--color-sentiment-content-primary)',
+                }}
+              >
+                {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>
+    ),
+  ],
+};
+
+export const AllVariants = storyConfig(
+  {
+    tags: ['!autodocs'],
+    parameters: {
+      padding: '0',
+      controls: { disable: true },
+    },
+    render: () => (
+      <div
+        className="sentiment-surface-variants"
+        style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '800px' }}
+      >
+        {sentiments.map((sentiment) =>
+          emphasisLevels.map((emphasis) => (
+            <SentimentSurface
+              key={`${sentiment}-${emphasis}`}
+              sentiment={sentiment}
+              emphasis={emphasis}
+              style={{ padding: '24px', borderRadius: '16px' }}
+            >
+              {sentiment} - {emphasis} emphasis
+            </SentimentSurface>
+          )),
+        )}
+      </div>
+    ),
+  },
+  { variants: ['default', 'dark', 'bright-green', 'forest-green'] },
+);

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

@@ -0,0 +1,123 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { expect, within } from 'storybook/test';
+import SentimentSurface from './SentimentSurface';
+import { storyConfig } from '../test-utils';
+
+export default {
+  component: SentimentSurface,
+  title: 'Content/SentimentSurface/Tests',
+} satisfies Meta<typeof SentimentSurface>;
+
+type Story = StoryObj<typeof SentimentSurface>;
+
+export const AllSentiments: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <SentimentSurface sentiment="negative">
+        Negative sentiment - Your payment has failed
+      </SentimentSurface>
+      <SentimentSurface sentiment="warning">
+        Warning sentiment - Action required on your account
+      </SentimentSurface>
+      <SentimentSurface sentiment="neutral">
+        Neutral sentiment - Your account is up to date
+      </SentimentSurface>
+      <SentimentSurface sentiment="success">
+        Success sentiment - Your payment was successful
+      </SentimentSurface>
+      <SentimentSurface sentiment="proposition">
+        Proposition sentiment - Try our new feature
+      </SentimentSurface>
+    </div>
+  ),
+};
+
+export const AllEmphasisLevels: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <SentimentSurface sentiment="neutral" emphasis="base">
+        Base emphasis (default)
+      </SentimentSurface>
+      <SentimentSurface sentiment="neutral" emphasis="elevated">
+        Elevated emphasis
+      </SentimentSurface>
+    </div>
+  ),
+};
+
+export const PolymorphicRendering: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Test that all elements are rendered with correct tags
+    const divElement = canvas.getByText('Rendered as div');
+    await expect(divElement.tagName).toBe('DIV');
+
+    const sectionElement = canvas.getByText('Rendered as section');
+    await expect(sectionElement.tagName).toBe('SECTION');
+
+    const articleElement = canvas.getByText('Rendered as article');
+    await expect(articleElement.tagName).toBe('ARTICLE');
+  },
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
+      <SentimentSurface sentiment="neutral">Rendered as div</SentimentSurface>
+      <SentimentSurface sentiment="success" as="section">
+        Rendered as section
+      </SentimentSurface>
+      <SentimentSurface sentiment="proposition" as="article">
+        Rendered as article
+      </SentimentSurface>
+    </div>
+  ),
+};
+
+export const AllVariants = storyConfig(
+  {
+    render: () => (
+      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px' }}>
+        {(['negative', 'warning', 'neutral', 'success', 'proposition'] as const).map(
+          (sentiment) => (
+            <div key={sentiment} style={{ display: 'contents' }}>
+              <SentimentSurface sentiment={sentiment} emphasis="base">
+                {sentiment} - base
+              </SentimentSurface>
+              <SentimentSurface sentiment={sentiment} emphasis="elevated">
+                {sentiment} - elevated
+              </SentimentSurface>
+            </div>
+          ),
+        )}
+      </div>
+    ),
+  },
+  { variants: ['default', 'dark'] },
+);
+
+export const NestedSentiments: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
+      <SentimentSurface sentiment="negative" emphasis="base">
+        Outer: Negative, base
+        <div style={{ margin: '16px 0 0 16px' }}>
+          <SentimentSurface sentiment="success" emphasis="elevated">
+            Inner: Success, elevated
+            <div style={{ margin: '12px 0 0 12px' }}>
+              <SentimentSurface sentiment="warning" emphasis="base">
+                Deepest: Warning, base
+              </SentimentSurface>
+            </div>
+          </SentimentSurface>
+        </div>
+      </SentimentSurface>
+      <SentimentSurface sentiment="proposition" emphasis="elevated">
+        Outer: Proposition, elevated
+        <div style={{ margin: '16px 0 0 16px' }}>
+          <SentimentSurface sentiment="neutral" emphasis="base">
+            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';