@transferwise/components 0.0.0-experimental-4b93e2b → 0.0.0-experimental-f144cf1

package/src/Snackbar/SnackbarProvider.test.tsx

@@ -0,0 +1,202 @@
+import { renderHook } from '@testing-library/react';
+
+import { act, mockMatchMedia, render, screen, userEvent } from '../test-utils';
+import { resetLiveRegionAnnouncementQueue } from '../common/LiveRegion/LiveRegion';
+
+import { SNACKBAR_EXIT_DURATION } from './constants';
+import type { SnackbarCreationProps } from './Snackbar.types';
+import SnackbarProvider from './SnackbarProvider';
+import useSnackbar from './useSnackbar';
+import useSnackbarManager from './useSnackbarManager';
+
+const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTimeAsync });
+
+mockMatchMedia();
+
+const advanceTimers = (duration: number) => {
+  act(() => {
+    jest.advanceTimersByTime(duration);
+  });
+};
+
+type SnackbarTrigger = {
+  label: string;
+  snackbar: SnackbarCreationProps;
+};
+
+const SnackbarTriggers = ({ triggers }: { triggers: SnackbarTrigger[] }) => {
+  const showSnackbar = useSnackbar();
+
+  return (
+    <>
+      {triggers.map(({ label, snackbar }) => (
+        <button key={label} type="button" onClick={() => showSnackbar(snackbar)}>
+          {label}
+        </button>
+      ))}
+    </>
+  );
+};
+
+const BatchedSnackbarTrigger = () => {
+  const showSnackbar = useSnackbar();
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        showSnackbar({ text: 'First message', duration: 'indefinite' });
+        showSnackbar({ text: 'Latest message', duration: 'indefinite' });
+      }}
+    >
+      Show latest
+    </button>
+  );
+};
+
+const renderProvider = (triggers: SnackbarTrigger[], timeout?: number) =>
+  render(
+    <SnackbarProvider timeout={timeout}>
+      <SnackbarTriggers triggers={triggers} />
+    </SnackbarProvider>,
+  );
+
+describe('SnackbarProvider orchestration', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    resetLiveRegionAnnouncementQueue();
+  });
+
+  afterEach(() => {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  it('creates a Snackbar programmatically', async () => {
+    renderProvider([
+      {
+        label: 'Show confirmation',
+        snackbar: { text: 'Changes saved', sentiment: 'success' },
+      },
+    ]);
+
+    await user.click(screen.getByRole('button', { name: 'Show confirmation' }));
+
+    expect(screen.getByRole('status')).toHaveTextContent('Changes saved');
+  });
+
+  it('uses an explicit semantic duration instead of the legacy Provider timeout', async () => {
+    renderProvider(
+      [
+        {
+          label: 'Show confirmation',
+          snackbar: { text: 'Changes saved', duration: 'default' },
+        },
+      ],
+      1,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Show confirmation' }));
+    advanceTimers(3999);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+
+    advanceTimers(1);
+    advanceTimers(SNACKBAR_EXIT_DURATION);
+    expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
+  });
+
+  it('retains an explicitly configured legacy Provider timeout', async () => {
+    renderProvider([{ label: 'Show confirmation', snackbar: { text: 'Changes saved' } }], 1000);
+
+    await user.click(screen.getByRole('button', { name: 'Show confirmation' }));
+    advanceTimers(999);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+
+    advanceTimers(1);
+    advanceTimers(SNACKBAR_EXIT_DURATION);
+    expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
+  });
+
+  it('exits the active Snackbar before showing the latest replacement', async () => {
+    renderProvider([
+      { label: 'Show first', snackbar: { text: 'First message', duration: 'indefinite' } },
+      { label: 'Show second', snackbar: { text: 'Second message', duration: 'indefinite' } },
+      { label: 'Show latest', snackbar: { text: 'Latest message', duration: 'indefinite' } },
+    ]);
+
+    await user.click(screen.getByRole('button', { name: 'Show first' }));
+    await user.click(screen.getByRole('button', { name: 'Show second' }));
+
+    expect(screen.getByText('First message')).toBeInTheDocument();
+    expect(screen.queryByText('Second message')).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: 'Show latest' }));
+    advanceTimers(SNACKBAR_EXIT_DURATION);
+
+    expect(screen.queryByText('First message')).not.toBeInTheDocument();
+    expect(screen.queryByText('Second message')).not.toBeInTheDocument();
+    expect(screen.getByText('Latest message')).toBeInTheDocument();
+  });
+
+  it('shows the latest Snackbar when multiple creations are batched before the first render', async () => {
+    render(
+      <SnackbarProvider>
+        <BatchedSnackbarTrigger />
+      </SnackbarProvider>,
+    );
+
+    await user.click(screen.getByRole('button', { name: 'Show latest' }));
+
+    expect(screen.queryByText('First message')).not.toBeInTheDocument();
+    expect(screen.getByText('Latest message')).toBeInTheDocument();
+  });
+
+  it('calls onDismiss after the active Snackbar finishes exiting', async () => {
+    const onDismiss = jest.fn();
+    renderProvider([
+      {
+        label: 'Show first',
+        snackbar: { text: 'First message', duration: 'indefinite', onDismiss },
+      },
+      { label: 'Replace', snackbar: { text: 'Replacement', duration: 'indefinite' } },
+    ]);
+
+    await user.click(screen.getByRole('button', { name: 'Show first' }));
+    await user.click(screen.getByRole('button', { name: 'Replace' }));
+    advanceTimers(SNACKBAR_EXIT_DURATION - 1);
+    expect(onDismiss).not.toHaveBeenCalled();
+
+    advanceTimers(1);
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it('promotes a pending Snackbar even when onDismiss throws', async () => {
+    const onDismiss = jest.fn(() => {
+      throw new Error('Dismiss callback failed');
+    });
+    const { result } = renderHook(() => useSnackbarManager());
+
+    await act(async () => result.current.showSnackbar({ text: 'First message', onDismiss }));
+    await act(async () => result.current.showSnackbar({ text: 'Replacement message' }));
+
+    await expect(act(async () => result.current.handleExited())).rejects.toThrow(
+      'Dismiss callback failed',
+    );
+    await act(async () => undefined);
+    expect(result.current.active?.props.text).toBe('Replacement message');
+    expect(result.current.visible).toBe(true);
+  });
+
+  it('cleans up the active Snackbar timer when the Provider unmounts', async () => {
+    const view = renderProvider([
+      { label: 'Show confirmation', snackbar: { text: 'Changes saved' } },
+    ]);
+
+    await user.click(screen.getByRole('button', { name: 'Show confirmation' }));
+    advanceTimers(300);
+    expect(jest.getTimerCount()).toBe(1);
+
+    view.unmount();
+    expect(jest.getTimerCount()).toBe(0);
+  });
+});

package/src/Snackbar/SnackbarProvider.tsx

@@ -1,38 +1,38 @@
-import { useMemo, useState } from 'react';
+import { useMemo } from 'react';
 
-import SnackbarPortal, { SnackbarProps } from './Snackbar';
 import { SnackbarContext } from './SnackbarContext';
+import { PortalledSnackbar } from './SnackbarPortal';
+import useSnackbarManager from './useSnackbarManager';
 
 export interface SnackbarProviderProps {
+  /**
+   * @deprecated Configure each Snackbar with semantic `duration` instead. Existing millisecond
+   * values remain supported temporarily while consumers migrate. A Snackbar's `duration` takes
+   * precedence when both are provided.
+   */
   timeout?: number;
+  /** Application content that can create Snackbars through the Provider context. */
   children?: React.ReactNode;
 }
 
-export default function SnackbarProvider({ timeout = 4500, children }: SnackbarProviderProps) {
-  const [state, setState] = useState<Omit<SnackbarProps, 'timeout'>>({
-    text: '',
-    timestamp: 0,
-  });
-  const { action, text, theme, timestamp } = state;
+export default function SnackbarProvider({ timeout, children }: SnackbarProviderProps) {
+  const { active, announcementKey, dismissSnackbar, handleExited, showSnackbar, visible } =
+    useSnackbarManager();
+  const contextValue = useMemo(() => ({ createSnackbar: showSnackbar }), [showSnackbar]);
 
   return (
-    <SnackbarContext.Provider
-      value={useMemo(
-        () => ({
-          createSnackbar: ({ action, text, theme }) => {
-            setState({ action, text, theme, timestamp: Date.now() });
-          },
-        }),
-        [],
-      )}
-    >
-      <SnackbarPortal
-        action={action}
-        text={text}
-        timestamp={timestamp}
-        timeout={timeout}
-        theme={theme}
-      />
+    <SnackbarContext.Provider value={contextValue}>
+      {active ? (
+        <PortalledSnackbar
+          key={active.id}
+          {...active.props}
+          announcementKey={announcementKey}
+          timeout={timeout}
+          visible={visible}
+          onDismissRequest={dismissSnackbar}
+          onExited={handleExited}
+        />
+      ) : null}
       {children}
     </SnackbarContext.Provider>
   );

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

@@ -0,0 +1,73 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Prompts/Snackbar/Accessibility" />
+
+# Accessibility
+
+Snackbar is a polite live region. It uses `role="status"` and `aria-live="polite"`, so its message
+is announced when the screen reader is idle without interrupting the current task. It does not move
+keyboard focus when it appears.
+
+Visual sentiment and announcement urgency are separate. A negative Snackbar remains polite; use a
+different component when an update is urgent enough to interrupt the user.
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Transfer failed',
+  sentiment: 'negative',
+});`}
+/>
+
+## Actions and dismissal
+
+The optional action uses its visible label as its accessible name. Keep the label concise and make
+the outcome clear. Timed Snackbars pause while the pointer is hovering over them or while keyboard
+focus is inside.
+
+The polite announcement tells screen-reader users that pressing `Escape` dismisses the Snackbar
+without moving focus. On desktop, the close button also has an accessible name and dismisses through
+the normal exit motion. On mobile, the Snackbar can be dismissed with a downward swipe. A swipe
+below 50% of its rendered height, an upward or horizontal gesture, or a cancelled gesture returns it
+to its resting position.
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Transfer deleted',
+  action: {
+    label: 'Undo',
+    onClick: handleUndo,
+  },
+  duration: 'extended',
+  onDismiss: handleDismiss,
+});`}
+/>
+
+## Media
+
+Default sentiment media already includes the appropriate accessible treatment. If custom media
+conveys meaning, add its accessibility attributes directly to the element you pass. Decorative
+custom media should be hidden from assistive technology.
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Added to your wallet',
+  media: <Card title="Card" />,
+});`}
+/>
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Offer applied',
+  media: <GiftBox aria-hidden />,
+});`}
+/>
+
+## Motion and zoom
+
+Snackbar removes movement and scaling when `prefers-reduced-motion: reduce` is enabled. Its content
+reflows at high zoom and narrow viewport widths without horizontal scrolling. Keep messages short
+and plain so they remain easy to read when text wraps.

package/src/Snackbar/_stories/Snackbar.rtl.test.story.tsx

@@ -1,4 +1,3 @@
-import { useEffect, useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-webpack5';
 
 import { withRTLDiff } from '../../../.storybook/decorators/RtlDiffDecorator';
@@ -12,21 +11,11 @@ export default {
 
 type Story = StoryObj<typeof Snackbar>;
 
-const TIMEOUT = 10_000_000;
-
 function SnackbarStory({ action }: { action?: { label: string } }) {
-  const [timestamp, setTimestamp] = useState(0);
-
-  useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect
-    setTimestamp(1);
-  }, []);
-
   return (
     <Snackbar
       text={<span>Transfer completed successfully</span>}
-      timestamp={timestamp}
-      timeout={TIMEOUT}
+      duration="indefinite"
       action={action}
     />
   );