@transferwise/components 0.0.0-experimental-bf3b43b → 0.0.0-experimental-cbc00a7

package/src/Snackbar/Snackbar.test.tsx

@@ -1,25 +1,39 @@
-import { act, render, screen, userEvent } from '../test-utils';
-import Button from '../Button';
+import { Card } from '@transferwise/icons';
 
-import { Snackbar, type SnackbarProps } from './Snackbar';
-import { SnackbarConsumer } from './SnackbarContext';
-import SnackbarProvider from './SnackbarProvider';
+import { act, mockMatchMedia, render, screen, userEvent } from '../test-utils';
+import { WDS_LIVE_REGION_DELAY_MS } from '../common/constants';
+import { resetLiveRegionAnnouncementQueue } from '../common/LiveRegion/LiveRegion';
 
-const CSS_TRANSITION_DURATION = 400;
-const TIMEOUT = 4000;
+import { SNACKBAR_EXIT_DURATION } from './constants';
+import { Snackbar } from './Snackbar';
+import type { SnackbarInternalProps } from './Snackbar.types';
 
+const TIMEOUT = 4500;
 const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTimeAsync });
 
+mockMatchMedia();
+
 const advanceTimers = (duration: number) => {
-  act(() => {
-    jest.advanceTimersByTime(duration);
-  });
+  act(() => jest.advanceTimersByTime(duration));
 };
 
-const renderSnackbar = (props: Partial<SnackbarProps> = {}) =>
-  render(<Snackbar text="" timeout={TIMEOUT} timestamp={0} {...props} />);
+const enableLiveRegion = () => advanceTimers(WDS_LIVE_REGION_DELAY_MS);
+
+const renderSnackbar = (props: Partial<SnackbarInternalProps> = {}) => {
+  const snackbarProps: SnackbarInternalProps = {
+    text: 'Changes saved',
+    timeout: TIMEOUT,
+    announcementKey: 1,
+    visible: true,
+    onDismissRequest: jest.fn(),
+    onExited: jest.fn(),
+    ...props,
+  };
+  return { ...render(<Snackbar {...snackbarProps} />), snackbarProps };
+};
 
 beforeEach(() => {
+  resetLiveRegionAnnouncementQueue();
   jest.useFakeTimers();
 });
 
@@ -28,179 +42,154 @@ afterEach(() => {
   jest.useRealTimers();
 });
 
-describe('Snackbar', () => {
-  it('renders the live region wrapper even while no notification is shown', () => {
-    renderSnackbar();
+describe('Snackbar controlled surface', () => {
+  it('renders no live region while not visible', () => {
+    renderSnackbar({ visible: false });
 
-    expect(screen.getByRole('alert')).toHaveAttribute('aria-live', 'assertive');
-    expect(screen.getByRole('alert')).toHaveClass('snackbar');
+    expect(screen.queryByRole('status')).not.toBeInTheDocument();
   });
 
-  it('does not show a notification that is already present on mount', () => {
-    renderSnackbar({ text: 'Changes saved', timestamp: 1 });
-
-    expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
-  });
-
-  it('shows the notification once text arrives after mount', () => {
-    const { rerender } = renderSnackbar();
-
-    rerender(<Snackbar text="Changes saved" timeout={TIMEOUT} timestamp={1} />);
+  it('renders the message when visible on mount', () => {
+    renderSnackbar();
 
     expect(screen.getByText('Changes saved')).toBeInTheDocument();
   });
 
   it('renders an action and calls its onClick handler', async () => {
     const onClick = jest.fn();
-    const { rerender } = renderSnackbar();
-
-    rerender(
-      <Snackbar
-        action={{ label: 'View', onClick }}
-        text="Transfer completed"
-        timeout={TIMEOUT}
-        timestamp={1}
-      />,
-    );
+    renderSnackbar({ action: { label: 'View', onClick } });
+
     await user.click(screen.getByRole('button', { name: 'View' }));
 
     expect(onClick).toHaveBeenCalledTimes(1);
   });
 
-  it('dismisses the notification once the timeout elapses', () => {
-    const { rerender } = renderSnackbar();
+  it('renders a navigation action with a React-node label', () => {
+    renderSnackbar({
+      action: { label: <span>View transfer</span>, href: '/transfers/123', target: '_blank' },
+    });
 
-    rerender(<Snackbar text="Changes saved" timeout={TIMEOUT} timestamp={1} />);
+    const link = screen.getByRole('link', { name: 'View transfer' });
+    expect(link).toHaveAttribute('href', '/transfers/123');
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+  });
 
-    advanceTimers(TIMEOUT - 1);
-    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+  it('calls a navigation action handler when activated with the keyboard', async () => {
+    const onClick: React.MouseEventHandler<HTMLAnchorElement> = jest.fn((event) => {
+      event.preventDefault();
+    });
+    renderSnackbar({ action: { label: 'View transfer', href: '/transfers/123', onClick } });
 
-    advanceTimers(1);
-    advanceTimers(CSS_TRANSITION_DURATION);
-    expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
-  });
+    screen.getByRole('link', { name: 'View transfer' }).focus();
+    await user.keyboard('{Enter}');
 
-  it('exits the current notification before entering the next one', () => {
-    const { rerender } = renderSnackbar();
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
 
-    rerender(<Snackbar text="First message" timeout={TIMEOUT} timestamp={1} />);
-    rerender(<Snackbar text="Second message" timeout={TIMEOUT} timestamp={2} />);
+  it('requests dismissal after the timeout without changing its own visibility', () => {
+    const onDismissRequest = jest.fn();
+    renderSnackbar({ onDismissRequest });
 
-    advanceTimers(CSS_TRANSITION_DURATION - 1);
-    expect(screen.queryByText('Second message')).not.toBeInTheDocument();
+    advanceTimers(TIMEOUT - 1);
+    expect(onDismissRequest).not.toHaveBeenCalled();
 
     advanceTimers(1);
-    expect(screen.getByText('Second message')).toBeInTheDocument();
-    expect(screen.queryByText('First message')).not.toBeInTheDocument();
+    expect(onDismissRequest).toHaveBeenCalledTimes(1);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
   });
 
-  it('shows the next notification immediately when the previous one has already been dismissed', () => {
-    const { rerender } = renderSnackbar();
+  it('clears the dismissal timer when it begins exiting', () => {
+    const onDismissRequest = jest.fn();
+    const { rerender, snackbarProps } = renderSnackbar({ onDismissRequest });
 
-    rerender(<Snackbar text="First message" timeout={TIMEOUT} timestamp={1} />);
-    advanceTimers(TIMEOUT + CSS_TRANSITION_DURATION);
+    rerender(<Snackbar {...snackbarProps} visible={false} />);
+    advanceTimers(TIMEOUT);
 
-    rerender(<Snackbar text="Second message" timeout={TIMEOUT} timestamp={2} />);
-    expect(screen.getByText('Second message')).toBeInTheDocument();
+    expect(onDismissRequest).not.toHaveBeenCalled();
   });
 
-  it('restarts the timeout for a replacing notification', () => {
-    const { rerender } = renderSnackbar();
-
-    rerender(<Snackbar text="First message" timeout={TIMEOUT} timestamp={1} />);
-    advanceTimers(TIMEOUT - 100);
-
-    rerender(<Snackbar text="Second message" timeout={TIMEOUT} timestamp={2} />);
-    advanceTimers(CSS_TRANSITION_DURATION);
-    expect(screen.getByText('Second message')).toBeInTheDocument();
+  it('notifies the provider only after its exit transition finishes', () => {
+    const onExited = jest.fn();
+    const { rerender, snackbarProps } = renderSnackbar({ onExited });
 
-    advanceTimers(TIMEOUT - 1);
-    expect(screen.getByText('Second message')).toBeInTheDocument();
+    rerender(<Snackbar {...snackbarProps} visible={false} />);
+    advanceTimers(SNACKBAR_EXIT_DURATION - 1);
+    expect(onExited).not.toHaveBeenCalled();
 
     advanceTimers(1);
-    advanceTimers(CSS_TRANSITION_DURATION);
-    expect(screen.queryByText('Second message')).not.toBeInTheDocument();
+    expect(onExited).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
   });
+});
 
-  it('dismisses a delayed replacement on the timeout current when it appears', () => {
-    const { rerender } = renderSnackbar();
-
-    rerender(<Snackbar text="First message" timeout={TIMEOUT} timestamp={1} />);
-    rerender(<Snackbar text="Second message" timeout={TIMEOUT} timestamp={2} />);
-    // Shortened while the replacement is still waiting out the exit transition.
-    rerender(<Snackbar text="Second message" timeout={1000} timestamp={2} />);
-
-    advanceTimers(CSS_TRANSITION_DURATION);
-    expect(screen.getByText('Second message')).toBeInTheDocument();
+describe('Snackbar live region', () => {
+  it('announces the notification as a polite status message', () => {
+    renderSnackbar();
+    const liveRegion = screen.getByRole('status');
 
-    advanceTimers(1000);
-    advanceTimers(CSS_TRANSITION_DURATION);
-    expect(screen.queryByText('Second message')).not.toBeInTheDocument();
+    expect(liveRegion).toHaveAttribute('aria-live', 'polite');
+    expect(liveRegion).toHaveAttribute('aria-atomic', 'true');
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
   });
 
-  // Documents existing behaviour rather than endorsing it: clearing the text leaves the notification
-  // on screen indefinitely, because the previous shouldComponentUpdate blocked the dismissal too.
-  it('keeps the notification visible for as long as text is empty', () => {
-    const { rerender } = renderSnackbar();
+  it('delays live-region exposure until assistive technology can observe the update', () => {
+    renderSnackbar();
+    const liveRegionContent = screen.getByRole('status').firstElementChild;
 
-    rerender(<Snackbar text="Changes saved" timeout={TIMEOUT} timestamp={1} />);
-    rerender(<Snackbar text="" timeout={TIMEOUT} timestamp={2} />);
+    expect(liveRegionContent).toHaveAttribute('aria-hidden', 'true');
+    advanceTimers(WDS_LIVE_REGION_DELAY_MS - 1);
+    expect(liveRegionContent).toHaveAttribute('aria-hidden', 'true');
 
-    advanceTimers(TIMEOUT + CSS_TRANSITION_DURATION);
-    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+    advanceTimers(1);
+    expect(liveRegionContent).not.toHaveAttribute('aria-hidden');
   });
 
-  it('ignores a repeated timestamp', () => {
-    const { rerender } = renderSnackbar();
-
-    rerender(<Snackbar text="First message" timeout={TIMEOUT} timestamp={1} />);
-    rerender(<Snackbar text="Second message" timeout={TIMEOUT} timestamp={1} />);
+  it('keeps interactive controls outside the delayed announcement subtree', () => {
+    renderSnackbar({ action: { label: 'Undo' } });
 
-    advanceTimers(CSS_TRANSITION_DURATION);
-    expect(screen.getByText('First message')).toBeInTheDocument();
-    expect(screen.queryByText('Second message')).not.toBeInTheDocument();
+    const liveRegionContent = screen.getByRole('status').firstElementChild;
+    const action = screen.getByRole('button', { name: 'Undo' });
+    const dismiss = screen.getByRole('button', { name: 'Close' });
+    expect(liveRegionContent).toHaveAttribute('aria-hidden', 'true');
+    expect(action.closest('[aria-hidden="true"]')).toBeNull();
+    expect(dismiss.closest('[aria-hidden="true"]')).toBeNull();
   });
+});
 
-  it('clears its pending dismissal timer on unmount', () => {
-    const { rerender, unmount } = renderSnackbar();
-
-    rerender(<Snackbar text="Changes saved" timeout={TIMEOUT} timestamp={1} />);
-    const pendingTimers = jest.getTimerCount();
-    unmount();
+describe('Snackbar media', () => {
+  it('uses the shared PrimitivePrompt structure', () => {
+    renderSnackbar();
+    enableLiveRegion();
 
-    // The timer left behind belongs to CSSTransition's enter timeout, not to Snackbar.
-    expect(jest.getTimerCount()).toBe(pendingTimers - 1);
+    expect(screen.getByText('Changes saved').closest('.wds-prompt')).toHaveClass(
+      'wds-Snackbar-container',
+    );
+    expect(screen.getByRole('button', { name: 'Close' })).toHaveClass('wds-prompt__dismiss');
   });
-});
 
-describe('Snackbar created through SnackbarProvider', () => {
-  const renderProvider = () =>
-    render(
-      <SnackbarProvider timeout={TIMEOUT}>
-        <SnackbarConsumer>
-          {({ createSnackbar }) => (
-            <Button onClick={() => createSnackbar({ text: 'Changes saved' })}>Show</Button>
-          )}
-        </SnackbarConsumer>
-      </SnackbarProvider>,
-    );
+  it('renders custom media in the fixed-size media wrapper', () => {
+    renderSnackbar({ media: <Card title="Card" /> });
 
-  it('shows a notification created through the context', async () => {
-    renderProvider();
+    expect(screen.getByTestId('card-icon').parentElement).toHaveClass('wds-Snackbar__media-asset');
+  });
 
-    await user.click(screen.getByRole('button', { name: 'Show' }));
+  it('renders proposition media in the fixed-size media wrapper', () => {
+    renderSnackbar({ sentiment: 'proposition' });
+    const icon = screen
+      .getByText('Changes saved')
+      .closest('.wds-prompt')
+      ?.querySelector('.tw-icon-tags');
 
-    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+    expect(icon?.parentElement).toHaveClass('wds-Snackbar__media-asset');
   });
 
-  it('shows only one notification when the trigger is clicked repeatedly', async () => {
-    renderProvider();
+  it('requests dismissal through the close button', async () => {
+    const onDismissRequest = jest.fn();
+    renderSnackbar({ onDismissRequest });
 
-    const trigger = screen.getByRole('button', { name: 'Show' });
-    await user.click(trigger);
-    await user.click(trigger);
-    await user.click(trigger);
+    await user.click(screen.getByRole('button', { name: 'Close' }));
 
-    expect(screen.getAllByRole('alert')).toHaveLength(1);
+    expect(onDismissRequest).toHaveBeenCalledTimes(1);
   });
 });

package/src/Snackbar/Snackbar.tsx

@@ -1,129 +1,128 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Tags } from '@transferwise/icons';
+import { useEffect, useRef } from 'react';
 import { CSSTransition } from 'react-transition-group';
 
 import Button from '../Button';
 import Body from '../Body';
+import { LiveRegion } from '../common';
 import type { ThemeDark, ThemeLight } from '../common';
-import withNextPortal from '../WithNextPortal/WithNextPortal';
+import { PrimitivePrompt } from '../Prompt/PrimitivePrompt';
+import type { Sentiment } from '../SentimentSurface';
+import StatusIcon from '../StatusIcon';
 
-const CSS_TRANSITION_DURATION = 400;
+import { SNACKBAR_ENTER_DURATION, SNACKBAR_EXIT_DURATION } from './constants';
+import type { SnackbarAction, SnackbarInternalProps } from './Snackbar.types';
 
 export interface SnackbarProps {
-  action?: {
-    label: string;
-    onClick?: React.MouseEventHandler<HTMLButtonElement>;
-  };
+  /** One optional action, supporting a callback or navigation through `href` and `target`. */
+  action?: SnackbarAction;
+  media?: React.ReactNode;
+  sentiment?: Sentiment;
   text: React.ReactNode;
   /** @deprecated Has no effect. Snackbar theming is based on ThemeProvider. */
   theme?: ThemeLight | ThemeDark;
   timeout: number;
-  timestamp: number;
-}
-
-interface SnackbarState extends Pick<SnackbarProps, 'action' | 'text'> {
-  visible: boolean;
+  /** @deprecated Has no effect when using SnackbarProvider, which manages Snackbar identity. */
+  timestamp?: number;
 }
 
-export const Snackbar = (props: SnackbarProps) => {
-  const bodyRef = useRef<HTMLSpanElement>(null);
-  const leaveTimeout = useRef(0);
-  const transitionTimeout = useRef(0);
-  /** The props of the last committed render, as `this.props` was in the class component. */
-  const committedProps = useRef(props);
-
-  const [state, setState] = useState<SnackbarState>({
-    visible: false,
-    text: '',
-  });
-
-  useEffect(
-    () => () => {
-      window.clearTimeout(leaveTimeout.current);
-      window.clearTimeout(transitionTimeout.current);
-    },
-    [],
-  );
-
-  // Runs after every render to mirror the componentDidUpdate lifecycle this component previously
-  // relied on, including the shouldComponentUpdate guard that ignored every update without text.
-  // Layout, not passive, so a notification is shown or replaced before the browser paints, as
-  // componentDidUpdate did. Both rules below are disabled on purpose: the dependency-less effect
-  // and its synchronous state updates are what keep this conversion behaviour-identical.
-  /* eslint-disable react-hooks/exhaustive-deps, react-hooks/set-state-in-effect */
-  useLayoutEffect(() => {
-    const previousProps = committedProps.current;
-    committedProps.current = props;
-
-    const { action, text, timestamp } = props;
-
-    // shouldComponentUpdate bailed out whenever the incoming text was empty. That also blocked the
-    // updates scheduled below, so a Snackbar whose text is cleared stays on screen until it is
-    // given text again. Preserved here deliberately to keep this refactor behaviour-identical.
-    const updateWhileTextIsPresent = (update: () => void) => {
-      if (committedProps.current.text) {
-        update();
-      }
-    };
-
-    const setLeaveTimeout = () => {
-      leaveTimeout.current = window.setTimeout(() => {
-        updateWhileTextIsPresent(() => setState((current) => ({ ...current, visible: false })));
-      }, committedProps.current.timeout);
-    };
+export const Snackbar = ({
+  action,
+  announcementKey,
+  media,
+  onDismissRequest,
+  onExited,
+  sentiment = 'neutral',
+  text,
+  timeout,
+  visible,
+}: SnackbarInternalProps) => {
+  const surfaceRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!visible) {
+      return undefined;
+    }
 
-    const show = () => {
-      setState((current) => ({ ...current, visible: true, action, text }));
-      setLeaveTimeout();
-    };
+    const id = window.setTimeout(onDismissRequest, timeout);
+    return () => window.clearTimeout(id);
+  }, [announcementKey, onDismissRequest, timeout, visible]);
 
-    if (!text) {
-      return;
+  const renderMedia = () => {
+    if (media) {
+      return <span className="wds-Snackbar__media-asset">{media}</span>;
     }
 
-    if (!previousProps.text) {
-      show();
-    } else if (previousProps.timestamp !== timestamp) {
-      window.clearTimeout(leaveTimeout.current);
-
-      if (state.visible) {
-        setState((current) => ({ ...current, visible: false }));
-        transitionTimeout.current = window.setTimeout(() => {
-          updateWhileTextIsPresent(show);
-        }, CSS_TRANSITION_DURATION);
-      } else {
-        show();
-      }
+    if (sentiment === 'proposition') {
+      return (
+        <span className="wds-Snackbar__media-asset">
+          <Tags aria-hidden size={24} />
+        </span>
+      );
     }
-  });
-  /* eslint-enable react-hooks/exhaustive-deps, react-hooks/set-state-in-effect */
 
-  const { action, text, visible } = state;
-  const { timeout } = props;
+    return <StatusIcon sentiment={sentiment} size={24} />;
+  };
 
   return (
-    <div className="snackbar" aria-live="assertive" role="alert">
+    <div
+      className="wds-Snackbar"
+      style={
+        {
+          '--Snackbar-enter-duration': `${SNACKBAR_ENTER_DURATION}ms`,
+          '--Snackbar-exit-duration': `${SNACKBAR_EXIT_DURATION}ms`,
+        } as React.CSSProperties
+      }
+    >
       <CSSTransition
-        nodeRef={bodyRef}
+        appear
+        nodeRef={surfaceRef}
         in={visible}
-        classNames="snackbar__text-container"
+        classNames="wds-Snackbar-container"
         timeout={{
-          appear: 0,
-          enter: timeout,
-          exit: CSS_TRANSITION_DURATION,
+          appear: SNACKBAR_ENTER_DURATION,
+          enter: SNACKBAR_ENTER_DURATION,
+          exit: SNACKBAR_EXIT_DURATION,
         }}
         unmountOnExit
+        onExited={onExited}
       >
-        <Body ref={bodyRef} as="span" className="snackbar__text">
-          {text}
-          {action ? (
-            <Button className="snackbar__text__action" v2 size="sm" onClick={action.onClick}>
-              {action.label}
-            </Button>
-          ) : null}
-        </Body>
+        <PrimitivePrompt
+          ref={surfaceRef}
+          className="wds-Snackbar-container"
+          sentiment={sentiment}
+          emphasis="elevated"
+          media={renderMedia()}
+          onDismiss={onDismissRequest}
+        >
+          <div className="wds-Snackbar__content">
+            <LiveRegion
+              aria-live="polite"
+              announceOnChange={announcementKey}
+              className="wds-Snackbar__message"
+            >
+              <Body as="span" className="wds-Snackbar__body">
+                {text}
+              </Body>
+            </LiveRegion>
+            {action ? (
+              <Button
+                className="wds-Snackbar__action"
+                v2
+                size="sm"
+                priority="secondary"
+                href={action.href}
+                target={action.target}
+                onClick={action.onClick}
+              >
+                {action.label}
+              </Button>
+            ) : null}
+          </div>
+        </PrimitivePrompt>
       </CSSTransition>
     </div>
   );
 };
 
-export default withNextPortal(Snackbar);
+export default Snackbar;

package/src/Snackbar/Snackbar.types.ts

@@ -0,0 +1,21 @@
+import type { ButtonProps, ButtonReferenceType } from '../Button/Button.types';
+import type { SnackbarProps } from './Snackbar';
+
+/** One optional action. Supports callbacks and navigation through the Button API. */
+export type SnackbarAction = Pick<ButtonProps, 'href' | 'target'> & {
+  label: ButtonProps['children'];
+  onClick?: React.MouseEventHandler<ButtonReferenceType>;
+};
+
+/** Props accepted by `createSnackbar` from `useSnackbar()`. */
+export type SnackbarCreationProps = Omit<SnackbarProps, 'timeout'>;
+
+/** Props the provider passes to control a Snackbar. Internal. */
+export interface SnackbarInternalProps extends Omit<SnackbarProps, 'timeout' | 'timestamp'> {
+  /** Changes for each new Snackbar so LiveRegion re-announces it. */
+  announcementKey: number;
+  onDismissRequest: () => void;
+  onExited: () => void;
+  timeout: number;
+  visible: boolean;
+}

package/src/Snackbar/SnackbarContext.ts

@@ -1,9 +1,9 @@
 import { createContext } from 'react';
 
-import { SnackbarProps } from './Snackbar';
+import type { SnackbarCreationProps } from './Snackbar.types';
 
 export type SnackbarContextType = {
-  createSnackbar: (props: Omit<SnackbarProps, 'timeout' | 'timestamp'>) => void;
+  createSnackbar: (props: SnackbarCreationProps) => void;
 };
 
 export const SnackbarContext = createContext<SnackbarContextType>({ createSnackbar: () => {} });

package/src/Snackbar/SnackbarPortal.tsx

@@ -0,0 +1,8 @@
+import withNextPortal from '../WithNextPortal/WithNextPortal';
+
+import { Snackbar } from './Snackbar';
+
+/** Renders the Snackbar into `document.body` after mount, so it's safe for SSR. */
+const SnackbarPortal = withNextPortal(Snackbar);
+
+export default SnackbarPortal;