@transferwise/components 46.116.0 → 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,46 +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',
-    style: { padding: '24px', borderRadius: '16px' },
   },
-  decorators: [withContainer],
   parameters: {
     docs: {
       toc: true,
@@ -94,86 +120,15 @@ 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 },
+    children: (
+      <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>
+    ),
   },
-  decorators: [withComponentGrid],
+  tags: ['!autodocs'],
 };
 
 const sentiments: Sentiment[] = ['negative', 'warning', 'neutral', 'success', 'proposition'];
@@ -240,31 +195,102 @@ 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 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 Tokens: Story = {
+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
             key={`${sentiment}-${emphasis}`}
             sentiment={sentiment}
             emphasis={emphasis}
-            style={{ padding: '24px', borderRadius: '16px' }}
+            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>
+            <h4
+              className="d-block m-b-2 text-capitalize np-text-title-body"
+              style={{
+                color: 'inherit',
+              }}
+            >
+              {sentiment} - {emphasis}
+            </h4>
             <div
               style={{
                 display: 'grid',
@@ -274,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} />
                   ))}
@@ -295,10 +322,15 @@ export const Tokens: Story = {
           </SentimentSurface>
         )),
       )}
-    </div>
+    </section>
   ),
   parameters: {
     controls: { disable: true },
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
   },
   decorators: [
     (Story: () => JSX.Element) => (
@@ -309,32 +341,178 @@ export const Tokens: Story = {
   ],
 };
 
-export const AllVariants = storyConfig(
-  {
-    tags: ['!autodocs'],
-    parameters: {
-      padding: '0',
-      controls: { disable: true },
+/**
+ * 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: () => (
-      <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>
-          )),
-        )}
+  },
+  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>
+    </>
+  );
+}
+`,
+      },
+    },
   },
-  { variants: ['default', 'dark', 'bright-green', 'forest-green'] },
-);
+};