@transferwise/components 46.116.1 → 46.117.0

package/src/sentimentSurface/SentimentSurface.story.tsx

@@ -1,14 +1,14 @@
 import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { Defrost } from '@transferwise/icons';
+import Body from '../body';
+import Button from '../button';
+import Header from '../header';
+import Link from '../link';
+import IconButton from '../iconButton';
+import StatusIcon from '../statusIcon';
 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={{
@@ -24,8 +24,9 @@ const withComponentGrid = (Story: () => JSX.Element) => (
 );
 
 /**
- * SentimentSurface is a polymorphic container component that applies contextual background colours
- * and text styling based on sentiment types.
+ * SentimentSurface is a polymorphic container component that exposes and, optionally, applies
+ * contextual colour tokens as CSS custom properties, based on sentiment types (`negative`,
+ * `warning`, `neutral`, `success`, `proposition`).
  */
 const meta: Meta<typeof SentimentSurface> = {
   component: SentimentSurface,
@@ -35,45 +36,71 @@ const meta: Meta<typeof SentimentSurface> = {
       control: 'select',
       options: ['negative', 'warning', 'neutral', 'success', 'proposition'],
       description: 'The sentiment type that determines the colour scheme',
+      table: {
+        type: { summary: 'Sentiment' },
+      },
     },
     emphasis: {
-      control: 'select',
+      control: 'inline-radio',
       options: ['base', 'elevated'],
       description: 'The emphasis level affecting background and text contrast',
       table: {
-        defaultValue: { summary: 'base' },
+        defaultValue: { summary: '"base"' },
       },
     },
-    as: {
-      control: 'text',
-      description: 'The underlying HTML element to render',
+    hasBaseStyles: {
+      control: 'boolean',
+      description:
+        'If true, sets the `background-color` and `color` on the container. Otherwise, only exposes the tokens as CSS custom properties without rendering.',
       table: {
-        defaultValue: { summary: 'div' },
+        defaultValue: { summary: 'true' },
       },
     },
-    children: {
+    as: {
       control: 'text',
-      description: 'Content to render inside the surface',
+      description: 'The underlying HTML element to render.',
+      table: {
+        defaultValue: {
+          summary: '"div"',
+        },
+        type: { summary: 'string' },
+      },
     },
     className: {
+      table: {
+        type: { summary: 'string' },
+      },
       control: 'text',
-      description: 'Additional CSS classes',
     },
     id: {
+      table: {
+        type: { summary: 'string' },
+      },
       control: 'text',
-      description: 'Unique identifier for the component',
     },
-    testId: {
+    'data-testid': {
       control: 'text',
-      description: 'Test ID for React Testing Library',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    children: {
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+      control: false,
     },
   },
   args: {
     sentiment: 'neutral',
     emphasis: 'base',
+    hasBaseStyles: undefined,
+    as: undefined,
+    className: undefined,
+    id: undefined,
+    'data-testid': undefined,
     children: 'This is a sentiment surface',
   },
-  decorators: [withContainer],
   parameters: {
     docs: {
       toc: true,
@@ -94,75 +121,14 @@ export const Playground: Story = {
     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 className="p-a-2">
+        This is a custom div demonstrating a sentiment surface. It exposes CSS custom properties for
+        the selected sentiment type and emphasis level and, optionally, applies background and text
+        colours.
       </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],
+  tags: ['!autodocs'],
 };
 
 const sentiments: Sentiment[] = ['negative', 'warning', 'neutral', 'success', 'proposition'];
@@ -229,12 +195,83 @@ const TokenSwatch = ({ token }: { token: string }) => (
 );
 
 /**
- * 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.
+ * Each sentiment type has two emphasis levels – `base` and `elevated` – to provide different levels of visual prominence.
+ *
+ * **When to use:**
+ *
+ * - `Base`: For inline notifications, subtle callouts, or when sentiment needs to be communicated without drawing too much attention
+ * - `Elevated`: For prominent banners, critical alerts, or when the sentiment should be immediately noticeable
+ *
  */
-export const Tokens: Story = {
+export const EmphasisLevels: Story = {
+  render: (args) => (
+    <>
+      <SentimentSurface {...args} sentiment="negative" emphasis="base">
+        <div className="p-a-2">Negative - Base emphasis</div>
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="negative" emphasis="elevated">
+        <div className="p-a-2">Negative - Elevated emphasis</div>
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success" emphasis="base">
+        <div className="p-a-2">Success - Base emphasis</div>
+      </SentimentSurface>
+      <SentimentSurface {...args} sentiment="success" emphasis="elevated">
+        <div className="p-a-2">Success - Elevated emphasis</div>
+      </SentimentSurface>
+    </>
+  ),
+  parameters: {
+    controls: { disable: true },
+  },
+  decorators: [withComponentGrid],
+};
+
+/**
+ * By default, `SentimentSurface` exposes the tokens as CSS custom properties and also applies
+ * the base styles for `background-color` and `color`.
+ * However, you can choose to only expose the CSS custom properties by setting the `hasBaseStyles`
+ * prop to `false`. This is useful when you want to create custom components that adapt to the
+ * sentiment context without applying default styles.
+ */
+export const BaseStyles: Story = {
+  render: (args) => (
+    <>
+      <SentimentSurface
+        sentiment="success"
+        style={{ border: `1px dashed var(--color-sentiment-content-primary)` }}
+      >
+        <div className="p-a-2">This example exposes and applies the tokens.</div>
+      </SentimentSurface>
+      <SentimentSurface
+        hasBaseStyles={false}
+        sentiment="success"
+        style={{ border: `1px dashed var(--color-sentiment-content-primary)` }}
+      >
+        <div className="p-a-2">This example only exposes the tokens without applying them.</div>
+        <div
+          className="p-a-2"
+          style={{
+            backgroundColor: 'var(--color-sentiment-background-surface)',
+            color: 'var(--color-sentiment-content-primary)',
+          }}
+        >
+          Which means you have to apply them yourself.
+        </div>
+      </SentimentSurface>
+    </>
+  ),
+  parameters: {
+    controls: { disable: true },
+  },
+  decorators: [withComponentGrid],
+};
+
+/**
+ * The component exposes token groups for all 5 sentiment types (`negative`, `warning`, `neutral`, `proposition` and `success`) each of them with two emphasis levels (`base` and `elevated`).
+ */
+export const ExposedTokens: Story = {
   render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '32px', maxWidth: '100%' }}>
+    <section style={{ display: 'flex', flexDirection: 'column', gap: '32px', maxWidth: '100%' }}>
       {sentiments.map((sentiment) =>
         emphasisLevels.map((emphasis) => (
           <SentimentSurface
@@ -244,20 +281,16 @@ export const Tokens: Story = {
             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>
+            <h4
+              className="d-block m-b-2 text-capitalize np-text-title-body"
+              style={{
+                color: 'inherit',
+              }}
+            >
+              {sentiment} - {emphasis}
+            </h4>
             <div
               style={{
                 display: 'grid',
@@ -267,18 +300,19 @@ export const Tokens: Story = {
             >
               {tokenCategories.map((category) => (
                 <div key={category.name}>
-                  <div
+                  <h5
                     style={{
+                      color: 'inherit',
                       fontSize: '12px',
                       fontWeight: 600,
                       marginBottom: '8px',
                       textTransform: 'uppercase',
                       letterSpacing: '0.5px',
-                      opacity: 0.7,
+                      opacity: 0.8,
                     }}
                   >
                     {category.name}
-                  </div>
+                  </h5>
                   {category.tokens.map((token) => (
                     <TokenSwatch key={token} token={token} />
                   ))}
@@ -288,10 +322,15 @@ export const Tokens: Story = {
           </SentimentSurface>
         )),
       )}
-    </div>
+    </section>
   ),
   parameters: {
     controls: { disable: true },
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
   },
   decorators: [
     (Story: () => JSX.Element) => (
@@ -301,3 +340,179 @@ export const Tokens: Story = {
     ),
   ],
 };
+
+/**
+ * Sentiment surfaces can be nested to create layered contexts. Each nested surface establishes its own colour context through CSS custom properties.
+ */
+export const NestingSurfaces: Story = {
+  parameters: {
+    controls: { disable: true },
+  },
+  render: (args) => {
+    return (
+      <SentimentSurface sentiment="success" emphasis="base" className="p-a-1">
+        Success base sentiment surface
+        <SentimentSurface sentiment="neutral" emphasis="elevated" className="p-a-1 m-t-1">
+          Neutral elevated sentiment surface
+          <SentimentSurface sentiment="warning" emphasis="base" className="p-a-1 m-t-1">
+            Warning base sentiment surface
+          </SentimentSurface>
+        </SentimentSurface>
+      </SentimentSurface>
+    );
+  },
+};
+
+/**
+ * Some DS components (namely `Button`, `StatusIcon`, and `IconButton`) automatically adapt to the sentiment context when used within a `SentimentSurface`.
+ */
+export const SentimentAwareComponents: Story = {
+  name: 'Sentiment-aware Components',
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  render: function Render(args) {
+    const inner = (
+      <div className="p-a-2 m-b-2 sentimentAwareComponent">
+        <Body>
+          This text and its <Link href="#">inline links</Link> should use sentiment-matched colour.
+        </Body>
+        <IconButton size={32}>
+          <Defrost />
+        </IconButton>
+        <StatusIcon size={32} sentiment="positive" />
+        <Button v2 priority="primary" size="sm">
+          Primary
+        </Button>
+        <Button v2 priority="secondary" size="sm">
+          Secondary
+        </Button>
+      </div>
+    );
+
+    return (
+      <>
+        <Header level="group" title="No sentiment surface" />
+        {inner}
+
+        <Header level="group" title="Success sentiment surface" />
+        <SentimentSurface sentiment="success">{inner}</SentimentSurface>
+
+        <Header level="group" title="Negative sentiment surface" />
+        <SentimentSurface sentiment="negative">{inner}</SentimentSurface>
+      </>
+    );
+  },
+  decorators: [
+    withComponentGrid,
+    (Story) => (
+      <>
+        <style>
+          {`
+            .sentimentAwareComponent {
+              display: flex;
+              flex-wrap: wrap;
+              gap: var(--size-8);
+              
+              >:first-child {
+                width: 100%;
+              }
+            }
+          `}
+        </style>
+        <Story />
+      </>
+    ),
+  ],
+};
+
+function CustomCard({ children, className }: { className?: string; children: React.ReactNode }) {
+  return (
+    <div
+      className={`p-a-1 d-flex align-items-center justify-content-between custom-card ${className}`}
+    >
+      {children}
+      <Button v2 size="sm">
+        Interact with me
+      </Button>
+    </div>
+  );
+}
+
+export const CustomComponents: Story = {
+  tags: ['!autodocs', '!dev'],
+  render: (args) => (
+    <>
+      <style>{`
+        .custom-card {
+          background-color: var(
+            --color-sentiment-background-surface,
+            var(--color-background-surface)
+          );
+          
+          color: var(
+            --color-sentiment-content-primary,
+            var(--color-content-primary)
+          );
+          
+          gap: var(--size-16);
+        }
+      `}</style>
+
+      <CustomCard className="m-b-2">This component works outside a SentimentSurface</CustomCard>
+
+      <SentimentSurface sentiment="negative">
+        <CustomCard>This component adapts to the context of the SentimentSurface</CustomCard>
+      </SentimentSurface>
+    </>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `
+// CSS
+.custom-card {
+  color: var(
+    --color-sentiment-content-primary,
+    var(--color-content-primary)
+  );
+  border: 1px solid var(
+    --color-sentiment-interactive-secondary,
+    var(--color-border-neutral)
+  );
+  gap: var(--size-16);
+}
+
+// JSX
+function CustomCard({ children }) {
+  return (
+    <div className="p-a-1 d-flex align-items-center justify-content-between custom-card">
+      {children}
+      <Button v2 size="sm">
+        Interact with me
+      </Button>
+    </div>
+  );
+}
+
+function View() {
+  return (
+    <>
+      <CustomCard>This card works outside a SentimentSurface</CustomCard>
+      
+      <SentimentSurface sentiment="negative">
+        <CustomCard>This card adapts to the warning sentiment</CustomCard>
+      </SentimentSurface>
+    </>
+  );
+}
+`,
+      },
+    },
+  },
+};

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

@@ -1,9 +1,28 @@
 import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { ThemeProvider, type Theming } from '@wise/components-theming';
 import SentimentSurface from './SentimentSurface';
+import Button from '../button';
+import type { Sentiment, Emphasis } from './SentimentSurface.types';
+
+const sentiments: Sentiment[] = ['negative', 'success', 'proposition', 'warning', 'neutral'];
+const emphasisLevels: Emphasis[] = ['base', 'elevated'];
+
+// Themes that support light/dark screen modes
+const themesWithScreenModes: Theming['theme'][] = ['personal', 'business', 'platform'];
+// Themes that don't have light/dark variants
+const themesWithoutScreenModes: Theming['theme'][] = [
+  'forest-green',
+  'bright-green',
+  'business--forest-green',
+  'business--bright-green',
+  'platform--forest-green',
+];
+const screenModes: Theming['screenMode'][] = ['light', 'dark'];
 
 export default {
   component: SentimentSurface,
   title: 'Content/SentimentSurface/Tests',
+  tags: ['!autodocs'],
 } satisfies Meta<typeof SentimentSurface>;
 
 type Story = StoryObj<typeof SentimentSurface>;
@@ -11,58 +30,23 @@ 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)',
-        }}
-      >
+      <SentimentSurface sentiment="negative" emphasis="base">
         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)',
-            }}
-          >
+          <SentimentSurface sentiment="success" emphasis="elevated">
             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)',
-                }}
-              >
+              <SentimentSurface sentiment="warning" emphasis="base">
                 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)',
-        }}
-      >
+      <SentimentSurface sentiment="proposition" emphasis="elevated">
         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)',
-            }}
-          >
+          <SentimentSurface sentiment="neutral" emphasis="base">
             Inner: Neutral, base
           </SentimentSurface>
         </div>
@@ -70,3 +54,69 @@ export const NestedSentiments: Story = {
     </div>
   ),
 };
+
+const ButtonsGrid = () => (
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+    {emphasisLevels.map((emphasis) =>
+      sentiments.map((sentiment) => (
+        <SentimentSurface
+          key={`${sentiment}-${emphasis}`}
+          sentiment={sentiment}
+          emphasis={emphasis}
+          style={{
+            backgroundColor: 'var(--color-sentiment-background-surface)',
+            color: 'var(--color-sentiment-content-primary)',
+            padding: '16px',
+          }}
+        >
+          <span
+            style={{
+              marginRight: '16px',
+              textTransform: 'capitalize',
+              minWidth: '150px',
+              display: 'inline-block',
+            }}
+          >
+            {sentiment} ({emphasis})
+          </span>
+          <Button v2>Primary</Button>
+          <Button v2 priority="secondary" style={{ marginLeft: '8px' }}>
+            Secondary
+          </Button>
+          <Button v2 priority="secondary-neutral" style={{ marginLeft: '8px' }}>
+            Secondary Neutral
+          </Button>
+        </SentimentSurface>
+      )),
+    )}
+  </div>
+);
+
+export const ButtonsAcrossThemes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '32px' }}>
+      {/* Themes with light/dark screen modes */}
+      {themesWithScreenModes.map((theme) =>
+        screenModes.map((screenMode) => (
+          <ThemeProvider key={`${theme}-${screenMode}`} theme={theme} screenMode={screenMode}>
+            <div style={{ padding: '16px' }}>
+              <h3 style={{ margin: '0 0 16px 0', textTransform: 'capitalize' }}>
+                {theme} - {screenMode}
+              </h3>
+              <ButtonsGrid />
+            </div>
+          </ThemeProvider>
+        )),
+      )}
+      {/* Themes without light/dark variants */}
+      {themesWithoutScreenModes.map((theme) => (
+        <ThemeProvider key={theme} theme={theme}>
+          <div style={{ padding: '16px' }}>
+            <h3 style={{ margin: '0 0 16px 0', textTransform: 'capitalize' }}>{theme}</h3>
+            <ButtonsGrid />
+          </div>
+        </ThemeProvider>
+      ))}
+    </div>
+  ),
+};