@transferwise/components 0.0.0-experimental-85015e0 → 0.0.0-experimental-7990d38

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

@@ -149,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

@@ -24,21 +24,18 @@ const launchSnackbar = async (canvasElement: HTMLElement) => {
 
 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 }) => (
             <>
@@ -47,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/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;