@transferwise/components 46.167.0 → 46.168.0

package/src/Prompt/Snackbar/SnackbarProvider.tsx

@@ -0,0 +1,41 @@
+import { useMemo } from 'react';
+
+import SnackbarPortal from './SnackbarPortal';
+import { SnackbarContext } from './SnackbarContext';
+import useSnackbarManager from './useSnackbarManager';
+
+export interface SnackbarProviderProps {
+  /**
+   * @deprecated Use per-Snackbar `duration` instead. Explicit millisecond values remain supported
+   * and are not automatically remapped when no `duration` is supplied.
+   * When neither option is supplied, the default is 4000ms (previously 4500ms), after entry finishes.
+   * To migrate, use `default` for 0–5000ms, `extended` for values above 5000ms, and `indefinite`
+   * for intentionally persistent notifications.
+   */
+  timeout?: number;
+  children?: React.ReactNode;
+}
+
+export default function SnackbarProvider({ timeout, children }: SnackbarProviderProps) {
+  const { active, announcementKey, createSnackbar, dismissSnackbar, handleExited, visible } =
+    useSnackbarManager();
+  const contextValue = useMemo(() => ({ createSnackbar }), [createSnackbar]);
+
+  return (
+    <SnackbarContext.Provider value={contextValue}>
+      {active ? (
+        <SnackbarPortal
+          // Each instance gets a fresh appear transition and live-region announcement.
+          key={active.id}
+          {...active.props}
+          announcementKey={announcementKey}
+          timeout={timeout}
+          visible={visible}
+          onDismissRequest={dismissSnackbar}
+          onExited={handleExited}
+        />
+      ) : null}
+      {children}
+    </SnackbarContext.Provider>
+  );
+}

package/src/Prompt/Snackbar/_stories/Snackbar.accessibility.docs.mdx

@@ -0,0 +1,58 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Prompts/Snackbar/Accessibility" />
+
+# Accessibility
+
+## Announcements
+
+Snackbar uses `role="status"`, `aria-live="polite"` and `aria-atomic="true"` for every sentiment,
+including negative. Showing a message requests a polite announcement without moving focus.
+There is no live region while the Provider is idle.
+
+The localised hint “Press Escape to dismiss.” follows the message, including on touch-only devices.
+
+## Keyboard and dismissal
+
+- The action follows normal tab order. Buttons support Enter and Space; links support Enter.
+- Escape dismisses unless another overlay has already handled it.
+- Desktop has a close IconButton labelled “Close”. On small screens it is hidden and not focusable.
+- Swipe or drag down at least half the surface height to dismiss. Shorter or cancelled gestures return to place.
+
+There is no shortcut to reach the action. Do not make Snackbar the only way to access an essential action.
+
+## Reduced motion
+
+Reduced motion removes entry/exit movement and scale, and swipe transitions.
+
+## Media
+
+Include essential meaning in the message: custom media is outside its live region.
+Hide decorative icons from assistive technology:
+
+<Source
+  dark
+  code={`import { Button, SnackbarProvider, useSnackbar } from '@transferwise/components';
+import { Card } from '@transferwise/icons';
+
+function CardFeedback() {
+  const createSnackbar = useSnackbar();
+
+  return (
+    <Button v2 size="md" onClick={() => createSnackbar({
+      text: 'Card added to your wallet',
+      media: <Card aria-hidden />,
+    })}>
+      Show card confirmation
+    </Button>
+  );
+}
+
+export default function App() {
+  return (
+    <SnackbarProvider>
+      <CardFeedback />
+    </SnackbarProvider>
+  );
+}`}
+/>

package/src/{Snackbar → Prompt/Snackbar}/_stories/Snackbar.rtl.test.story.tsx

@@ -1,8 +1,11 @@
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-webpack5';
 
-import { useRtlDiffI18n, withRTLDiff } from '../../../.storybook/decorators/RtlDiffDecorator';
+import { useRtlDiffI18n, withRTLDiff } from '../../../../.storybook/decorators/RtlDiffDecorator';
 import { Snackbar } from '../Snackbar';
+import type { SnackbarCreationProps } from '../Snackbar.types';
+import SnackbarProvider from '../SnackbarProvider';
+import useSnackbar from '../useSnackbar';
 
 export default {
   component: Snackbar,
@@ -12,18 +15,23 @@ export default {
 
 type Story = StoryObj<typeof Snackbar>;
 
-const TIMEOUT = 10_000_000;
-
-function SnackbarStory({ text, action }: { text: string; action?: { label: string } }) {
-  const [timestamp, setTimestamp] = useState(0);
+function ShowOnMount(props: SnackbarCreationProps) {
+  const createSnackbar = useSnackbar();
 
   useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect
-    setTimestamp(1);
+    createSnackbar(props);
+    // This visual fixture creates once per mount, not on every render of its props.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  return null;
+}
+
+function SnackbarStory({ text, action }: { text: string; action?: { label: string } }) {
   return (
-    <Snackbar text={<span>{text}</span>} timestamp={timestamp} timeout={TIMEOUT} action={action} />
+    <SnackbarProvider>
+      <ShowOnMount text={<span>{text}</span>} action={action} duration="indefinite" />
+    </SnackbarProvider>
   );
 }
 

package/src/Prompt/Snackbar/_stories/Snackbar.story.tsx

@@ -0,0 +1,416 @@
+import type { Meta, StoryObj } from '@storybook/react-webpack5';
+import { fn } from 'storybook/test';
+import { Card } from '@transferwise/icons';
+
+import {
+  createSandboxStory,
+  globalScope,
+} from '../../../../.storybook/components/sandbox/SandboxEditor';
+import Button from '../../../Button';
+import { Snackbar } from '../Snackbar';
+import type { SnackbarCreationProps } from '../Snackbar.types';
+import SnackbarProvider from '../SnackbarProvider';
+import useSnackbar from '../useSnackbar';
+
+const meta = {
+  component: Snackbar,
+  title: 'Prompts/Snackbar',
+  tags: ['new'],
+  parameters: {
+    docs: {
+      description: {
+        component: `Snackbar provides short feedback after an action, with one optional action of its own.
+Use \`useSnackbar()\` inside \`SnackbarProvider\`. A newer message replaces the current one; Snackbars do not stack.
+
+Change the Playground controls, then click **Show Snackbar** to try them. Keep messages short and plain.
+
+See [Accessibility](?path=/docs/prompts-snackbar-accessibility--docs) for keyboard and announcement behaviour.`,
+      },
+    },
+  },
+  argTypes: {
+    text: { control: 'text', table: { type: { summary: 'ReactNode' } } },
+    sentiment: {
+      control: 'select',
+      options: ['neutral', 'success', 'warning', 'negative', 'proposition'],
+    },
+    duration: { control: 'select', options: ['default', 'extended', 'indefinite'] },
+    loading: { control: 'boolean' },
+    media: { control: false, table: { type: { summary: 'ReactNode' } } },
+    action: {
+      control: false,
+      table: {
+        type: {
+          summary: 'SnackbarAction',
+          detail:
+            '{ label: ReactNode; href?: string; target?: string; onClick?: MouseEventHandler }',
+        },
+      },
+    },
+    onDismiss: { control: false },
+    announcementKey: { table: { disable: true } },
+    onDismissRequest: { table: { disable: true } },
+    onExited: { table: { disable: true } },
+    visible: { table: { disable: true } },
+    timeout: { table: { disable: true } },
+    timestamp: { table: { disable: true } },
+    theme: { table: { disable: true } },
+  },
+} satisfies Meta<typeof Snackbar>;
+
+export default meta;
+
+type PreviewStoryArgs = Pick<
+  SnackbarCreationProps,
+  'sentiment' | 'duration' | 'loading' | 'onDismiss'
+> & {
+  text: string;
+  previewMedia: 'default' | 'card';
+  previewActionLabel: string;
+  previewActionHref: string;
+};
+
+function SnackbarTrigger({
+  label = 'Show Snackbar',
+  ...props
+}: SnackbarCreationProps & { label?: string }) {
+  const createSnackbar = useSnackbar();
+
+  return (
+    <Button v2 size="md" onClick={() => createSnackbar(props)}>
+      {label}
+    </Button>
+  );
+}
+
+const onActionClick = fn();
+
+type SnackbarExample = SnackbarCreationProps & { label: string };
+
+function SnackbarExamples({ examples }: { examples: SnackbarExample[] }) {
+  return (
+    <SnackbarProvider>
+      <div className="d-flex flex-wrap" style={{ gap: 'var(--size-8)' }}>
+        {examples.map(({ label, ...props }) => (
+          <SnackbarTrigger key={label} label={label} {...props} />
+        ))}
+      </div>
+    </SnackbarProvider>
+  );
+}
+
+const getExamplesCode = (examples: string, withMedia = false) =>
+  `import { Button, SnackbarProvider, useSnackbar } from '@transferwise/components';
+${withMedia ? "import { Card } from '@transferwise/icons';\n" : ''}
+function App() {
+  return (
+    <SnackbarProvider>
+      <ShowExamples />
+    </SnackbarProvider>
+  );
+}
+
+function ShowExamples() {
+  const createSnackbar = useSnackbar();
+  const examples = ${examples};
+
+  return (
+    <div className="d-flex flex-wrap" style={{ gap: 'var(--size-8)' }}>
+      {examples.map(({ label, ...props }) => (
+        <Button key={label} v2 size="md" onClick={() => createSnackbar(props)}>
+          {label}
+        </Button>
+      ))}
+    </div>
+  );
+}
+
+export default App;`;
+
+const getExampleCode = ({
+  text,
+  sentiment,
+  duration,
+  loading,
+  previewMedia,
+  previewActionLabel,
+  previewActionHref,
+}: PreviewStoryArgs) => `function App() {
+  return (
+    <SnackbarProvider>
+      <ShowSnackbar />
+    </SnackbarProvider>
+  );
+}
+
+function ShowSnackbar() {
+  const createSnackbar = useSnackbar();
+
+  return (
+    <Button v2 size="md" onClick={() => createSnackbar({
+      text: ${JSON.stringify(text)},
+      sentiment: ${JSON.stringify(sentiment)},
+      duration: ${JSON.stringify(duration)},${loading ? '\n      loading: true,' : ''}${previewMedia === 'card' ? '\n      media: <Card aria-hidden />,' : ''}${
+        previewActionLabel
+          ? `
+      action: {
+        label: ${JSON.stringify(previewActionLabel)},${previewActionHref ? `\n        href: ${JSON.stringify(previewActionHref)},` : ''}
+        onClick: () => console.log('Action clicked'),
+      },`
+          : ''
+      }
+      onDismiss: () => console.log('Dismissed'),
+    })}>
+      Show Snackbar
+    </Button>
+  );
+}`;
+
+/** Change the controls, then click Show Snackbar to create a message with those values. */
+export const Playground: StoryObj<PreviewStoryArgs> = {
+  args: {
+    text: 'Changes saved',
+    sentiment: 'success',
+    duration: 'default',
+    loading: false,
+    previewMedia: 'default',
+    previewActionLabel: '',
+    previewActionHref: '',
+    onDismiss: fn(),
+  },
+  argTypes: {
+    previewMedia: {
+      name: 'Preview with custom media',
+      control: 'select',
+      options: ['default', 'card'],
+      table: { category: 'Storybook Preview options' },
+    },
+    previewActionLabel: {
+      name: 'Action label (empty for no action)',
+      control: 'text',
+      table: { category: 'Storybook Preview options' },
+    },
+    previewActionHref: {
+      name: 'Action href (empty for callback only)',
+      control: 'text',
+      table: { category: 'Storybook Preview options' },
+    },
+  },
+  render: ({ previewMedia, previewActionLabel, previewActionHref, ...props }) => (
+    <SnackbarProvider>
+      <SnackbarTrigger
+        {...props}
+        media={previewMedia === 'card' ? <Card aria-hidden /> : undefined}
+        action={
+          previewActionLabel
+            ? {
+                label: previewActionLabel,
+                href: previewActionHref || undefined,
+                onClick: onActionClick,
+              }
+            : undefined
+        }
+      />
+    </SnackbarProvider>
+  ),
+  parameters: {
+    chromatic: { disableSnapshot: true },
+    docs: {
+      source: {
+        type: 'dynamic',
+        transform: (source: string, { args }: { args: PreviewStoryArgs }) =>
+          `import { Button, SnackbarProvider, useSnackbar } from '@transferwise/components';\n${args.previewMedia === 'card' ? "import { Card } from '@transferwise/icons';\n" : ''}\n${getExampleCode(args)}\n\nexport default App;`,
+      },
+    },
+  },
+};
+
+export const Sandbox = createSandboxStory({
+  code: getExampleCode({
+    text: 'Card added',
+    sentiment: 'neutral',
+    duration: 'extended',
+    previewMedia: 'card',
+    previewActionLabel: 'View',
+    previewActionHref: '',
+  }),
+  scope: globalScope,
+});
+
+/**
+ * Choose a sentiment to match the message. Each has default media; all use polite announcements.
+ * Show one at a time using the buttons below.
+ */
+export const Sentiments: StoryObj = {
+  render: () => (
+    <SnackbarExamples
+      examples={(['neutral', 'success', 'warning', 'negative', 'proposition'] as const).map(
+        (sentiment) => ({ label: sentiment, sentiment, text: 'Your details have been updated' }),
+      )}
+    />
+  ),
+  parameters: {
+    controls: { disable: true },
+    chromatic: { disableSnapshot: true },
+    docs: {
+      source: {
+        code: getExamplesCode(`(['neutral', 'success', 'warning', 'negative', 'proposition'] as const).map(
+    (sentiment) => ({ label: sentiment, sentiment, text: 'Your details have been updated' }),
+  )`),
+      },
+    },
+  },
+};
+
+/**
+ * Default media follows the sentiment. Override it with a custom icon, including for neutral and
+ * proposition. Wise icons fill the 24×24px slot without an explicit size.
+ */
+export const MediaTypes: StoryObj = {
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        { label: 'Default media', text: 'Changes saved', sentiment: 'success' },
+        { label: 'Custom neutral', text: 'Card added', media: <Card aria-hidden /> },
+        {
+          label: 'Custom proposition',
+          text: 'Your new card is ready',
+          sentiment: 'proposition',
+          media: <Card aria-hidden />,
+        },
+      ]}
+    />
+  ),
+  parameters: {
+    controls: { disable: true },
+    chromatic: { disableSnapshot: true },
+    docs: {
+      source: {
+        code: getExamplesCode(
+          `[
+    { label: 'Default media', text: 'Changes saved', sentiment: 'success' as const },
+    { label: 'Custom neutral', text: 'Card added', media: <Card aria-hidden /> },
+    {
+      label: 'Custom proposition',
+      text: 'Your new card is ready',
+      sentiment: 'proposition' as const,
+      media: <Card aria-hidden />,
+    },
+  ]`,
+          true,
+        ),
+      },
+    },
+  },
+};
+
+/** Loading replaces media, uses neutral styling and prevents auto-dismiss, regardless of duration. */
+export const Loading: StoryObj<PreviewStoryArgs> = {
+  ...Playground,
+  args: { ...Playground.args, text: 'Uploading document', loading: true },
+};
+
+/**
+ * Add one action: a callback with `onClick`, navigation with `href`, or both.
+ * Activating it requests dismissal after the callback runs.
+ */
+export const WithAction: StoryObj = {
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        {
+          label: 'Callback action',
+          text: 'Transfer deleted',
+          duration: 'extended',
+          action: { label: 'Undo', onClick: onActionClick },
+        },
+        {
+          label: 'Navigation action',
+          text: 'Your transfer is ready',
+          duration: 'extended',
+          action: { label: 'View transfer', href: '/transfers/123', target: '_blank' },
+        },
+      ]}
+    />
+  ),
+  parameters: {
+    controls: { disable: true },
+    chromatic: { disableSnapshot: true },
+    docs: {
+      source: {
+        code: getExamplesCode(`[
+    {
+      label: 'Callback action',
+      text: 'Transfer deleted',
+      duration: 'extended' as const,
+      action: { label: 'Undo', onClick: () => console.log('Undo clicked') },
+    },
+    {
+      label: 'Navigation action',
+      text: 'Your transfer is ready',
+      duration: 'extended' as const,
+      action: { label: 'View transfer', href: '/transfers/123', target: '_blank' },
+    },
+  ]`),
+      },
+    },
+  },
+};
+
+/**
+ * `default` lasts 4 seconds, `extended` lasts 6, and `indefinite` has no timer.
+ * Timers begin after entry and pause during hover, focus or a swipe, then resume with the remaining time.
+ */
+export const Durations: StoryObj = {
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        { label: 'Default (4s)', text: 'Changes saved', duration: 'default' },
+        {
+          label: 'Extended (6s)',
+          text: 'Transfer deleted',
+          duration: 'extended',
+          action: { label: 'Undo', onClick: onActionClick },
+        },
+        {
+          label: 'Indefinite',
+          text: 'Uploading document',
+          duration: 'indefinite',
+          loading: true,
+        },
+      ]}
+    />
+  ),
+  parameters: {
+    controls: { disable: true },
+    chromatic: { disableSnapshot: true },
+    docs: {
+      source: {
+        code: getExamplesCode(`[
+    { label: 'Default (4s)', text: 'Changes saved', duration: 'default' as const },
+    {
+      label: 'Extended (6s)',
+      text: 'Transfer deleted',
+      duration: 'extended' as const,
+      action: { label: 'Undo', onClick: () => console.log('Undo clicked') },
+    },
+    {
+      label: 'Indefinite',
+      text: 'Uploading document',
+      duration: 'indefinite' as const,
+      loading: true,
+    },
+  ]`),
+      },
+    },
+  },
+};
+
+/**
+ * Dismiss with Escape, the desktop close button, an action, or a downward swipe/drag of at least half
+ * the surface height. `onDismiss` fires after exit; check the Actions panel to see it.
+ */
+export const Dismissal: StoryObj<PreviewStoryArgs> = {
+  ...Playground,
+  args: { ...Playground.args, duration: 'indefinite' },
+};