@transferwise/components 0.0.0-experimental-cf159cc → 0.0.0-experimental-7990d38

package/src/Snackbar/Snackbar.tsx

@@ -1,5 +1,4 @@
 import { Tags } from '@transferwise/icons';
-import { useEffect, useRef } from 'react';
 import { CSSTransition } from 'react-transition-group';
 
 import Button from '../Button';
@@ -11,17 +10,31 @@ import type { Sentiment } from '../SentimentSurface';
 import StatusIcon from '../StatusIcon';
 
 import { SNACKBAR_ENTER_DURATION, SNACKBAR_EXIT_DURATION } from './constants';
-import type { SnackbarAction, SnackbarInternalProps } from './Snackbar.types';
+import type { SnackbarAction, SnackbarDuration } from './Snackbar.types';
+import useSnackbarAutoDismiss from './useSnackbarAutoDismiss';
 
 /**
- * Message options retained for public type compatibility. Create notifications through
- * SnackbarProvider/useSnackbar; the controlled surface also needs provider-only lifecycle props.
+ * Props for the controlled Snackbar surface, including provider-managed lifecycle controls.
+ * Use SnackbarCreationProps when creating notifications through SnackbarProvider/useSnackbar.
  */
 export interface SnackbarProps {
   /** One optional action, supporting a callback or navigation through `href` and `target`. */
   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;
   /** Overrides sentiment-derived media with content for the 24×24px media slot. */
   media?: React.ReactNode;
+  /** 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'
@@ -31,15 +44,23 @@ export interface SnackbarProps {
   text: React.ReactNode;
   /** @deprecated Has no effect. Snackbar theming is based on ThemeProvider. */
   theme?: ThemeLight | ThemeDark;
-  /** Auto-dismiss delay in milliseconds, supplied by the provider. */
-  timeout: number;
+  /**
+   * @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 = ({
   action,
   announcementKey,
+  duration,
   media,
   onDismissRequest,
   onExited,
@@ -47,17 +68,15 @@ export const Snackbar = ({
   text,
   timeout,
   visible,
-}: SnackbarInternalProps) => {
-  const surfaceRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!visible) {
-      return undefined;
-    }
-
-    const id = window.setTimeout(onDismissRequest, timeout);
-    return () => window.clearTimeout(id);
-  }, [announcementKey, onDismissRequest, timeout, visible]);
+}: SnackbarProps) => {
+  const { handleBlur, handleEntered, handleFocus, handleMouseEnter, handleMouseLeave, surfaceRef } =
+    useSnackbarAutoDismiss({
+      duration,
+      onDismissRequest,
+      resetKey: announcementKey,
+      timeout,
+      visible,
+    });
 
   const renderMedia = () => {
     if (media) {
@@ -96,6 +115,7 @@ export const Snackbar = ({
           exit: SNACKBAR_EXIT_DURATION,
         }}
         unmountOnExit
+        onEntered={handleEntered}
         onExited={onExited}
       >
         <PrimitivePrompt
@@ -105,6 +125,10 @@ export const Snackbar = ({
           emphasis="elevated"
           media={renderMedia()}
           onDismiss={onDismissRequest}
+          onMouseEnter={handleMouseEnter}
+          onMouseLeave={handleMouseLeave}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
         >
           <div className="wds-Snackbar__content">
             <LiveRegion

package/src/Snackbar/Snackbar.types.ts

@@ -1,6 +1,9 @@
 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'];
@@ -8,18 +11,7 @@ export type SnackbarAction = Pick<ButtonProps, 'href' | 'target'> & {
 };
 
 /** 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;
-  /** 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;
-  /** Auto-dismiss delay in milliseconds, supplied by the provider. */
-  timeout: number;
-  /** Controls entry/exit; the surface does not manage visibility itself. */
-  visible: boolean;
-}
+export type SnackbarCreationProps = Omit<
+  SnackbarProps,
+  'announcementKey' | 'onDismissRequest' | 'onExited' | 'timeout' | 'visible'
+>;

package/src/Snackbar/SnackbarProvider.test.tsx

@@ -3,13 +3,18 @@ import { renderHook } from '@testing-library/react';
 import { act, mockMatchMedia, render, screen, userEvent } from '../test-utils';
 import { resetLiveRegionAnnouncementQueue } from '../common/LiveRegion/LiveRegion';
 
-import { SNACKBAR_ENTER_DURATION, SNACKBAR_EXIT_DURATION } from './constants';
+import {
+  SNACKBAR_DEFAULT_DURATION,
+  SNACKBAR_ENTER_DURATION,
+  SNACKBAR_EXIT_DURATION,
+  SNACKBAR_EXTENDED_DURATION,
+} from './constants';
 import type { SnackbarCreationProps } from './Snackbar.types';
 import SnackbarProvider from './SnackbarProvider';
 import useSnackbar from './useSnackbar';
 import useSnackbarManager from './useSnackbarManager';
 
-const TIMEOUT = 4500;
+const TIMEOUT = SNACKBAR_DEFAULT_DURATION;
 const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTimeAsync });
 
 mockMatchMedia();
@@ -114,10 +119,11 @@ describe('SnackbarProvider orchestration', () => {
     );
   });
 
-  it('keeps the default timeout until semantic durations are introduced', async () => {
+  it('dismisses after the default four-second duration', async () => {
     renderProvider([{ label: 'Show', snackbar: { text: 'Changes saved' } }]);
     await user.click(screen.getByRole('button', { name: 'Show' }));
 
+    advanceTimers(SNACKBAR_ENTER_DURATION);
     advanceTimers(TIMEOUT - 1);
     expect(screen.getByText('Changes saved')).toBeInTheDocument();
 
@@ -131,6 +137,7 @@ describe('SnackbarProvider orchestration', () => {
     renderProvider([{ label: 'Show', snackbar: { text: 'Changes saved' } }], TIMEOUT * 2);
     await user.click(screen.getByRole('button', { name: 'Show' }));
 
+    advanceTimers(SNACKBAR_ENTER_DURATION);
     advanceTimers(TIMEOUT * 2 - 1);
     expect(screen.getByText('Changes saved')).toBeInTheDocument();
 
@@ -139,6 +146,58 @@ describe('SnackbarProvider orchestration', () => {
     expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
   });
 
+  it('uses an explicit semantic duration instead of the legacy Provider timeout', async () => {
+    renderProvider(
+      [{ label: 'Show', snackbar: { text: 'Changes saved', duration: 'extended' } }],
+      1,
+    );
+    await user.click(screen.getByRole('button', { name: 'Show' }));
+
+    advanceTimers(SNACKBAR_ENTER_DURATION);
+    advanceTimers(SNACKBAR_EXTENDED_DURATION - 1);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+    advanceTimers(1);
+    advanceTimers(SNACKBAR_EXIT_DURATION);
+    expect(screen.queryByText('Changes saved')).not.toBeInTheDocument();
+  });
+
+  it('pauses the provider timer while keyboard focus moves within the Snackbar', async () => {
+    renderProvider([
+      { label: 'Show', snackbar: { text: 'Changes saved', action: { label: 'Undo' } } },
+    ]);
+    await user.click(screen.getByRole('button', { name: 'Show' }));
+    advanceTimers(SNACKBAR_ENTER_DURATION);
+    advanceTimers(TIMEOUT / 2);
+
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Undo' })).toHaveFocus();
+    advanceTimers(TIMEOUT * 2);
+    await user.tab();
+    expect(screen.getByRole('button', { name: 'Close' })).toHaveFocus();
+    advanceTimers(TIMEOUT * 2);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+
+    await user.tab();
+    advanceTimers(TIMEOUT / 2 - 1);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+    advanceTimers(1);
+    advanceTimers(SNACKBAR_EXIT_DURATION);
+    expect(document.querySelector('.wds-Snackbar')).toBeNull();
+  });
+
+  it('keeps indefinite notifications until manually dismissed', async () => {
+    renderProvider([
+      { label: 'Show', snackbar: { text: 'Changes saved', duration: 'indefinite' } },
+    ]);
+    await user.click(screen.getByRole('button', { name: 'Show' }));
+
+    advanceTimers(60_000);
+    expect(screen.getByText('Changes saved')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Close' }));
+    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' } },
@@ -203,6 +262,7 @@ describe('SnackbarProvider orchestration', () => {
     await user.click(screen.getByRole('button', { name: 'Replace' }));
     advanceTimers(SNACKBAR_EXIT_DURATION);
 
+    advanceTimers(SNACKBAR_ENTER_DURATION);
     advanceTimers(TIMEOUT - 1);
     expect(screen.getByText('Replacement')).toBeInTheDocument();
     advanceTimers(1);
@@ -292,7 +352,7 @@ describe('SnackbarProvider orchestration', () => {
         <SnackbarTriggers triggers={triggers} />
       </SnackbarProvider>,
     );
-    advanceTimers(TIMEOUT - SNACKBAR_ENTER_DURATION);
+    advanceTimers(TIMEOUT);
     advanceTimers(SNACKBAR_EXIT_DURATION);
 
     expect(document.querySelector('.wds-Snackbar')).toBeNull();

package/src/Snackbar/SnackbarProvider.tsx

@@ -5,11 +5,18 @@ 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 = 4500, children }: SnackbarProviderProps) {
+export default function SnackbarProvider({ timeout, children }: SnackbarProviderProps) {
   const { active, announcementKey, createSnackbar, dismissSnackbar, handleExited, visible } =
     useSnackbarManager();
   const contextValue = useMemo(() => ({ createSnackbar }), [createSnackbar]);

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

@@ -15,8 +15,6 @@ export default {
 
 type Story = StoryObj<typeof Snackbar>;
 
-const TIMEOUT = 10_000_000;
-
 function ShowOnMount(props: SnackbarCreationProps) {
   const createSnackbar = useSnackbar();
 
@@ -31,8 +29,8 @@ function ShowOnMount(props: SnackbarCreationProps) {
 
 function SnackbarStory({ text, action }: { text: string; action?: { label: string } }) {
   return (
-    <SnackbarProvider timeout={TIMEOUT}>
-      <ShowOnMount text={<span>{text}</span>} action={action} />
+    <SnackbarProvider>
+      <ShowOnMount text={<span>{text}</span>} action={action} duration="indefinite" />
     </SnackbarProvider>
   );
 }

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

@@ -8,7 +8,8 @@ import {
   globalScope,
 } from '../../../.storybook/components/sandbox/SandboxEditor';
 import Button from '../../Button';
-import { Snackbar, type SnackbarProps } from '../Snackbar';
+import { Snackbar } from '../Snackbar';
+import type { SnackbarCreationProps } from '../Snackbar.types';
 import { SnackbarConsumer } from '../SnackbarContext';
 import SnackbarProvider from '../SnackbarProvider';
 
@@ -20,7 +21,7 @@ export default meta;
 
 type SnackbarExample = {
   label: string;
-  props: Omit<SnackbarProps, 'timeout' | 'timestamp'>;
+  props: Omit<SnackbarCreationProps, 'timestamp'>;
 };
 
 const SnackbarExamples = ({ examples }: { examples: SnackbarExample[] }) => (
@@ -148,3 +149,40 @@ export const Media: StoryObj = {
     />
   ),
 };
+
+/**
+ * `duration` uses four-second, six-second or indefinite presets, counted after entry finishes.
+ * Timed Snackbars pause while hovered or focused and resume when both interactions end.
+ */
+export const Durations: StoryObj = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The default duration is now **4000ms**, previously **4500ms**, when neither `duration` nor a legacy Provider `timeout` is supplied. ' +
+          'Timed durations begin after the entry transition finishes, pause while hovered or focused, and resume with the remaining time only after both interactions end.\n\n' +
+          '`timeout` is deprecated but explicit millisecond values remain supported without automatic remapping. An explicit `duration` takes precedence. ' +
+          'When migrating, choose `default` for 0–5000ms, `extended` for values above 5000ms, and `indefinite` for intentionally persistent notifications.',
+      },
+    },
+  },
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        { label: 'Default (4s)', props: { text: 'Changes saved', duration: 'default' } },
+        {
+          label: 'Extended (6s)',
+          props: {
+            text: 'Transfer deleted',
+            duration: 'extended',
+            action: { label: 'Undo', onClick: fn() },
+          },
+        },
+        {
+          label: 'Indefinite',
+          props: { text: 'Waiting for confirmation', duration: 'indefinite' },
+        },
+      ]}
+    />
+  ),
+};

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

@@ -4,7 +4,8 @@ import { withVariantConfig } from '../../../.storybook/helpers';
 import { lorem20 } from '../../test-utils';
 import { wait } from '../../test-utils/wait';
 import Button from '../../Button';
-import { Snackbar, type SnackbarProps } from '../Snackbar';
+import { Snackbar } from '../Snackbar';
+import type { SnackbarCreationProps } from '../Snackbar.types';
 import { SnackbarConsumer } from '../SnackbarContext';
 import SnackbarProvider from '../SnackbarProvider';
 
@@ -21,23 +22,20 @@ const launchSnackbar = async (canvasElement: HTMLElement) => {
   await userEvent.click(canvas.getByRole('button'));
 };
 
-type Args = Partial<SnackbarProps> & {
+type Args = Partial<SnackbarCreationProps> & {
   extraContext: React.ReactNode;
-  timeout: number;
 };
 
-const TIMEOUT = 10000000;
-
 const Default = {
   args: {
-    timeout: TIMEOUT,
+    duration: 'indefinite',
   } as Args,
   play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
     await launchSnackbar(canvasElement);
   },
   render: (args: Args) => {
     return (
-      <SnackbarProvider timeout={args.timeout}>
+      <SnackbarProvider>
         <SnackbarConsumer>
           {({ createSnackbar }) => (
             <>
@@ -46,6 +44,7 @@ const Default = {
                 block
                 onClick={() => {
                   createSnackbar({
+                    duration: args.duration,
                     action: args.action ?? {
                       label: 'View',
                       onClick: () => action('View button clicked.'),

package/src/Snackbar/constants.ts

@@ -1,2 +1,7 @@
 export const SNACKBAR_ENTER_DURATION = 300;
 export const SNACKBAR_EXIT_DURATION = 150;
+
+/** Default auto-dismiss duration for short feedback, in milliseconds. */
+export const SNACKBAR_DEFAULT_DURATION = 4000;
+/** Extended auto-dismiss duration for messages needing more reading time, in milliseconds. */
+export const SNACKBAR_EXTENDED_DURATION = 6000;

package/src/Snackbar/index.ts

@@ -1,4 +1,4 @@
 export { default } from './Snackbar';
 
-export type { SnackbarProps } from './Snackbar';
+export type { SnackbarCreationProps } from './Snackbar.types';
 export type { SnackbarProviderProps } from './SnackbarProvider';

package/src/Snackbar/useSnackbarAutoDismiss.ts

@@ -0,0 +1,152 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+import { SNACKBAR_DEFAULT_DURATION, SNACKBAR_EXTENDED_DURATION } from './constants';
+import type { SnackbarDuration } from './Snackbar.types';
+
+type UseSnackbarAutoDismissOptions = {
+  duration?: SnackbarDuration;
+  onDismissRequest: () => void;
+  resetKey: number;
+  timeout?: number;
+  visible: boolean;
+};
+
+const getAutoDismissDuration = ({
+  duration,
+  timeout,
+}: Pick<UseSnackbarAutoDismissOptions, 'duration' | 'timeout'>) => {
+  if (duration === 'indefinite') {
+    return null;
+  }
+
+  if (duration === 'extended') {
+    return SNACKBAR_EXTENDED_DURATION;
+  }
+
+  if (duration === 'default') {
+    return SNACKBAR_DEFAULT_DURATION;
+  }
+
+  return timeout ?? SNACKBAR_DEFAULT_DURATION;
+};
+
+/** Starts after entry finishes and pauses on hover or focus, preserving the remaining time. */
+const useSnackbarAutoDismiss = ({
+  duration,
+  onDismissRequest,
+  resetKey,
+  timeout,
+  visible,
+}: UseSnackbarAutoDismissOptions) => {
+  const surfaceRef = useRef<HTMLDivElement>(null);
+  const hasEnteredRef = useRef(false);
+  const timeoutRef = useRef(0);
+  const remainingDurationRef = useRef<number | null>(null);
+  const timerStartedAtRef = useRef(0);
+  const interactionStateRef = useRef({ focusWithin: false, hovered: false });
+
+  const isInterrupted = useCallback(() => {
+    const { focusWithin, hovered } = interactionStateRef.current;
+    return focusWithin || hovered;
+  }, []);
+
+  const clearTimer = useCallback(() => {
+    window.clearTimeout(timeoutRef.current);
+    timeoutRef.current = 0;
+  }, []);
+
+  const startTimer = useCallback(
+    (remainingDuration = getAutoDismissDuration({ duration, timeout })) => {
+      clearTimer();
+      remainingDurationRef.current = remainingDuration;
+
+      if (!visible || !hasEnteredRef.current || remainingDuration === null || isInterrupted()) {
+        return;
+      }
+
+      timerStartedAtRef.current = Date.now();
+      timeoutRef.current = window.setTimeout(() => {
+        timeoutRef.current = 0;
+        remainingDurationRef.current = 0;
+        onDismissRequest();
+      }, remainingDuration);
+    },
+    [clearTimer, duration, isInterrupted, onDismissRequest, timeout, visible],
+  );
+
+  const pauseTimer = useCallback(() => {
+    if (!timeoutRef.current || remainingDurationRef.current === null) {
+      return;
+    }
+
+    clearTimer();
+    // Count only unpaused time; resuming must not grant another full duration.
+    remainingDurationRef.current = Math.max(
+      0,
+      remainingDurationRef.current - (Date.now() - timerStartedAtRef.current),
+    );
+  }, [clearTimer]);
+
+  const resumeTimer = useCallback(() => {
+    if (isInterrupted() || remainingDurationRef.current === null) {
+      return;
+    }
+
+    startTimer(remainingDurationRef.current);
+  }, [isInterrupted, startTimer]);
+
+  const handleMouseEnter = useCallback(() => {
+    interactionStateRef.current = { ...interactionStateRef.current, hovered: true };
+    pauseTimer();
+  }, [pauseTimer]);
+
+  const handleMouseLeave = useCallback(() => {
+    interactionStateRef.current = { ...interactionStateRef.current, hovered: false };
+    resumeTimer();
+  }, [resumeTimer]);
+
+  const handleFocus = useCallback(() => {
+    interactionStateRef.current = { ...interactionStateRef.current, focusWithin: true };
+    pauseTimer();
+  }, [pauseTimer]);
+
+  const handleBlur = useCallback(
+    (event: React.FocusEvent<HTMLDivElement>) => {
+      if (event.currentTarget.contains(event.relatedTarget)) {
+        return;
+      }
+
+      interactionStateRef.current = { ...interactionStateRef.current, focusWithin: false };
+      resumeTimer();
+    },
+    [resumeTimer],
+  );
+
+  const handleEntered = useCallback(() => {
+    hasEnteredRef.current = true;
+    const snackbar = surfaceRef.current;
+    // Entry can finish beneath the pointer or with keyboard focus already inside the surface.
+    interactionStateRef.current = {
+      focusWithin: Boolean(snackbar?.contains(document.activeElement)),
+      hovered: snackbar?.matches(':hover') ?? false,
+    };
+    startTimer();
+  }, [startTimer]);
+
+  useEffect(() => {
+    if (!visible) {
+      hasEnteredRef.current = false;
+      clearTimer();
+      return undefined;
+    }
+
+    // Before onEntered this only prepares the duration; it cannot start the countdown.
+    startTimer();
+
+    return clearTimer;
+  }, [clearTimer, resetKey, startTimer, visible]);
+
+  return { handleBlur, handleEntered, handleFocus, handleMouseEnter, handleMouseLeave, surfaceRef };
+};
+
+export default useSnackbarAutoDismiss;

package/src/index.ts

@@ -135,7 +135,7 @@ export type {
   SelectProps,
 } from './_deprecated/Select';
 export type { SlidingPanelProps } from './SlidingPanel';
-export type { SnackbarProps, SnackbarProviderProps } from './Snackbar';
+export type { SnackbarCreationProps, SnackbarProviderProps } from './Snackbar';
 export type { SnackbarContextType } from './Snackbar/SnackbarContext';
 export type { StatusIconProps, StatusIconSentiment } from './StatusIcon';
 export type { StickyProps } from './Sticky';