@transferwise/components 0.0.0-experimental-c20c070 → 0.0.0-experimental-b2b287d

package/src/Snackbar/Snackbar.tsx

@@ -1,129 +1,244 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Tags } from '@transferwise/icons';
+import { useEffect } from 'react';
+import { useIntl } from 'react-intl';
 import { CSSTransition } from 'react-transition-group';
 
-import Button from '../Button';
+import Button, { type ButtonReferenceType } from '../Button';
 import Body from '../Body';
+import { LiveRegion } from '../common';
 import type { ThemeDark, ThemeLight } from '../common';
-import withNextPortal from '../WithNextPortal/WithNextPortal';
-
-const CSS_TRANSITION_DURATION = 400;
-
+import { PrimitivePrompt } from '../Prompt/PrimitivePrompt';
+import ProcessIndicator from '../ProcessIndicator';
+import type { Sentiment } from '../SentimentSurface';
+import StatusIcon from '../StatusIcon';
+
+import { SNACKBAR_ENTER_DURATION, SNACKBAR_EXIT_DURATION } from './constants';
+import messages from './Snackbar.messages';
+import type { SnackbarAction, SnackbarDuration } from './Snackbar.types';
+import useSnackbarAutoDismiss from './useSnackbarAutoDismiss';
+import useSnackbarSwipeDismiss from './useSnackbarSwipeDismiss';
+
+/**
+ * Props for the controlled Snackbar surface, including provider-managed lifecycle controls.
+ * Use SnackbarCreationProps when creating notifications through SnackbarProvider/useSnackbar.
+ */
 export interface SnackbarProps {
-  action?: {
-    label: string;
-    onClick?: React.MouseEventHandler<HTMLButtonElement>;
-  };
+  /** One optional callback or navigation action. Activating it dismisses after its callback runs. */
+  action?: SnackbarAction;
+  /** Changes for each new Snackbar so LiveRegion re-announces it. */
+  announcementKey: number;
+  /**
+   * Controls auto-dismiss with a four-second, six-second or indefinite duration after entry finishes.
+   * Takes precedence over the deprecated `timeout`.
+   * When neither option is supplied, the default is 4000ms (previously 4500ms).
+   * @default 'default'
+   */
+  duration?: SnackbarDuration;
+  /**
+   * Replaces the media with a progress indicator, uses neutral styling and prevents auto-dismiss.
+   * Takes precedence over `media`, `sentiment`, `duration` and the deprecated `timeout`.
+   * @default false
+   */
+  loading?: boolean;
+  /** Overrides sentiment-derived media with content for the 24×24px media slot. */
+  media?: React.ReactNode;
+  /**
+   * Called once after this Snackbar finishes exiting, including after an action (e.g. Undo)
+   * or replacement by a newer Snackbar. The action callback runs first.
+   * Not called for Snackbars discarded before being shown, such as earlier creates batched
+   * before the first render.
+   */
+  onDismiss?: () => void;
+  /** Requests an exit; the provider retains the surface until onExited confirms it has finished. */
+  onDismissRequest: () => void;
+  /** Called after the exit animation so the provider can unmount active or show its replacement. */
+  onExited: () => void;
+  /**
+   * Controls the sentiment surface and default media.
+   * @default 'neutral'
+   */
+  sentiment?: Sentiment;
+  /** Message content. Empty strings or absent text dismiss without creating a blank replacement. */
   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'> {
+  /**
+   * @deprecated Use `duration` instead. Explicit millisecond values remain supported and are not
+   * automatically remapped when no `duration` is supplied.
+   * To migrate, use `default` for 0–5000ms, `extended` for values above 5000ms, and `indefinite`
+   * for intentionally persistent notifications.
+   */
+  timeout?: number;
+  /** @deprecated Has no effect when using SnackbarProvider, which manages Snackbar identity. */
+  timestamp?: number;
+  /** Controls entry/exit; the surface does not manage visibility itself. */
   visible: boolean;
 }
 
-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: '',
+export const Snackbar = ({
+  action,
+  announcementKey,
+  duration,
+  loading = false,
+  media,
+  onDismissRequest,
+  onExited,
+  sentiment = 'neutral',
+  text,
+  timeout,
+  visible,
+}: SnackbarProps) => {
+  const { formatMessage } = useIntl();
+  const {
+    handleBlur,
+    handleEntered,
+    handleFocus,
+    handleMouseEnter,
+    handleMouseLeave,
+    setSwiping,
+    surfaceRef,
+  } = useSnackbarAutoDismiss({
+    duration,
+    loading,
+    onDismissRequest,
+    timeout,
+    visible,
   });
+  const {
+    clearSwipePosition,
+    containerRef,
+    handleClickCapture,
+    handlePointerCancel,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+  } = useSnackbarSwipeDismiss({ onDismissRequest, onSwipeChange: setSwiping, visible });
+
+  useEffect(() => {
+    if (!visible) {
+      return undefined;
+    }
 
-  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 handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && !event.defaultPrevented && !event.isComposing) {
+        onDismissRequest();
       }
     };
 
-    const setLeaveTimeout = () => {
-      leaveTimeout.current = window.setTimeout(() => {
-        updateWhileTextIsPresent(() => setState((current) => ({ ...current, visible: false })));
-      }, committedProps.current.timeout);
-    };
+    // Let document-level overlays consume Escape before this fallback handles it.
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [visible, onDismissRequest]);
 
-    const show = () => {
-      setState((current) => ({ ...current, visible: true, action, text }));
-      setLeaveTimeout();
-    };
+  const handleActionClick: React.MouseEventHandler<ButtonReferenceType> = (event) => {
+    try {
+      action?.onClick?.(event);
+    } finally {
+      onDismissRequest();
+    }
+  };
 
-    if (!text) {
-      return;
+  const renderMedia = () => {
+    if (loading) {
+      return (
+        <ProcessIndicator
+          className="wds-Snackbar__process-indicator"
+          data-testid="Snackbar_ProcessIndicator"
+          size="xs"
+        />
+      );
     }
 
-    if (!previousProps.text) {
-      show();
-    } else if (previousProps.timestamp !== timestamp) {
-      window.clearTimeout(leaveTimeout.current);
+    if (media) {
+      return <span className="wds-Snackbar__media-asset">{media}</span>;
+    }
 
-      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
+      ref={containerRef}
+      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
+        onEntered={handleEntered}
+        onExited={() => {
+          clearSwipePosition();
+          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={loading ? 'neutral' : sentiment}
+          emphasis="elevated"
+          media={renderMedia()}
+          onDismiss={onDismissRequest}
+          onMouseEnter={handleMouseEnter}
+          onMouseLeave={handleMouseLeave}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+          onClickCapture={handleClickCapture}
+          onDragStart={(event) => event.preventDefault()}
+          onPointerDown={visible ? handlePointerDown : undefined}
+          onPointerMove={handlePointerMove}
+          onPointerUp={handlePointerUp}
+          onPointerCancel={handlePointerCancel}
+        >
+          <div className="wds-Snackbar__content">
+            <LiveRegion
+              aria-live="polite"
+              announceOnChange={announcementKey}
+              className="wds-Snackbar__message"
+            >
+              <Body as="span" className="wds-Snackbar__body">
+                {text}
+                <span className="sr-only"> {formatMessage(messages.escapeDismissHint)}</span>
+              </Body>
+            </LiveRegion>
+            {action ? (
+              <Button
+                className="wds-Snackbar__action"
+                v2
+                size="sm"
+                priority="secondary"
+                href={action.href}
+                target={action.target}
+                onClick={handleActionClick}
+              >
+                {action.label}
+              </Button>
+            ) : null}
+          </div>
+        </PrimitivePrompt>
       </CSSTransition>
     </div>
   );
 };
 
-export default withNextPortal(Snackbar);
+export default Snackbar;

package/src/Snackbar/Snackbar.types.ts

@@ -0,0 +1,17 @@
+import type { ButtonProps, ButtonReferenceType } from '../Button/Button.types';
+import type { SnackbarProps } from './Snackbar';
+
+/** Semantic auto-dismiss durations. `indefinite` disables the timer. */
+export type SnackbarDuration = 'default' | 'extended' | 'indefinite';
+
+/** 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,
+  'announcementKey' | 'onDismissRequest' | 'onExited' | 'timeout' | 'visible'
+>;

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;