@transferwise/components 0.0.0-experimental-63c3fc6 → 0.0.0-experimental-5f03867

package/src/Snackbar/SnackbarProvider.tsx

@@ -1,32 +1,40 @@
-import { useMemo, useState } from 'react';
+import { useMemo } from 'react';
 
-import SnackbarPortal, { SnackbarProps } from './Snackbar';
+import SnackbarPortal from './SnackbarPortal';
 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) {
-  const [state, setState] = useState<Omit<SnackbarProps, 'timeout'>>({
-    text: '',
-    timestamp: 0,
-  });
-  const { action, text, timestamp } = state;
+export default function SnackbarProvider({ timeout, children }: SnackbarProviderProps) {
+  const { active, announcementKey, createSnackbar, dismissSnackbar, handleExited, visible } =
+    useSnackbarManager();
+  const contextValue = useMemo(() => ({ createSnackbar }), [createSnackbar]);
 
   return (
-    <SnackbarContext.Provider
-      value={useMemo(
-        () => ({
-          createSnackbar: ({ action, text }) => {
-            setState({ action, text, timestamp: Date.now() });
-          },
-        }),
-        [],
-      )}
-    >
-      <SnackbarPortal action={action} text={text} timestamp={timestamp} timeout={timeout} />
+    <SnackbarContext.Provider value={contextValue}>
+      {active ? (
+        <SnackbarPortal
+          // Each instance gets a fresh appear transition and live-region announcement.
+          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,66 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Prompts/Snackbar/Accessibility" />
+
+# Accessibility
+
+## Announcements
+
+Snackbar uses `role="status"`, `aria-live="polite"` and `aria-atomic="true"` for every sentiment,
+including negative. Showing a message requests a polite announcement without moving focus.
+There is no live region while the Provider is idle.
+
+The localised hint “Press Escape to dismiss.” follows the message, including on touch-only devices.
+Touch-specific wording and a small-screen close button are follow-up work in
+[DS-8650](https://transferwise.atlassian.net/browse/DS-8650).
+
+## Keyboard and dismissal
+
+- The action follows normal tab order. Buttons support Enter and Space; links support Enter.
+- Escape dismisses unless another overlay has already handled it.
+- Desktop has a close IconButton labelled “Close”. On small screens it is hidden and not focusable.
+- Swipe or drag down at least half the surface height to dismiss. Shorter or cancelled gestures return to place.
+
+There is no shortcut to reach the action. Do not make Snackbar the only way to access an essential action;
+focus management is tracked in [DS-8622](https://transferwise.atlassian.net/browse/DS-8622).
+
+## Timing and motion
+
+Timed messages start counting after entry and pause during hover, keyboard focus or a swipe.
+Use `extended` for additional reading time or an action, and `indefinite` for persistent feedback.
+Loading always prevents auto-dismiss; describe the progress in the message, not just the spinner.
+
+Reduced motion removes entry/exit movement and scale, and swipe transitions. Check zoom/reflow and RTL
+with your content; the visual test stories provide examples.
+
+## Media
+
+Include essential meaning in the message: custom media is outside its live region.
+Hide decorative icons from assistive technology:
+
+<Source
+  dark
+  code={`import { Button, SnackbarProvider, useSnackbar } from '@transferwise/components';
+import { Card } from '@transferwise/icons';
+
+function CardFeedback() {
+  const createSnackbar = useSnackbar();
+
+  return (
+    <Button v2 size="md" onClick={() => createSnackbar({
+      text: 'Card added to your wallet',
+      media: <Card aria-hidden />,
+    })}>
+      Show card confirmation
+    </Button>
+  );
+}
+
+export default function App() {
+  return (
+    <SnackbarProvider>
+      <CardFeedback />
+    </SnackbarProvider>
+  );
+}`}
+/>

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

@@ -0,0 +1,64 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Prompts/Snackbar/Migration" />
+
+# Migration
+
+Existing `createSnackbar({ text, action })` calls continue to work with the updated design.
+
+## Imports
+
+- Replace the public `SnackbarProps` type with `SnackbarCreationProps`.
+- Direct `Snackbar` and `SnackbarPortal` exports are removed. Use `SnackbarProvider` and `useSnackbar()` instead.
+- The Provider, hook, Consumer, Context and their existing public types remain supported.
+  The hook still returns `createSnackbar` directly, not an object.
+
+Wrap your app in one Provider and call the hook from a component inside it:
+
+<Source
+  dark
+  code={`import { Button, SnackbarProvider, useSnackbar } from '@transferwise/components';
+import type { SnackbarCreationProps } from '@transferwise/components';
+
+const savedMessage: SnackbarCreationProps = {
+  text: 'Changes saved',
+  sentiment: 'success',
+};
+
+function SaveButton() {
+  const createSnackbar = useSnackbar();
+
+  return (
+    <Button v2 size="md" onClick={() => createSnackbar(savedMessage)}>
+      Show confirmation
+    </Button>
+  );
+}
+
+export default function App() {
+  return (
+    <SnackbarProvider>
+      <SaveButton />
+    </SnackbarProvider>
+  );
+}`}
+/>
+
+## Duration
+
+The default changes from **4500ms to 4000ms**, counted after entry finishes.
+Replace deprecated Provider `timeout` values with a per-message `duration`:
+
+- `default`: 4 seconds, generally replacing 0–5000ms.
+- `extended`: 6 seconds, for more reading time or an action, generally replacing values above 5000ms.
+- `indefinite`: no timer, for intentionally persistent messages, including very large timeouts used to avoid expiry.
+
+Explicit Provider timeouts still work and are **not automatically remapped**. A message's `duration`
+takes precedence; `loading: true` always prevents auto-dismiss.
+
+## Other changes
+
+- `theme` and `timestamp` remain accepted but are deprecated and have no effect with the Provider.
+- An empty string clears the current message and any waiting replacement.
+- Review CSS and tests targeting the old `snackbar` DOM/classes: these now use `wds-Snackbar` and the shared prompt structure.
+- Announcements change from assertive alerts to polite status messages. See [Accessibility](?path=/docs/prompts-snackbar-accessibility--docs).

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

@@ -1,8 +1,11 @@
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-webpack5';
 
 import { useRtlDiffI18n, withRTLDiff } from '../../../.storybook/decorators/RtlDiffDecorator';
 import { Snackbar } from '../Snackbar';
+import type { SnackbarCreationProps } from '../Snackbar.types';
+import SnackbarProvider from '../SnackbarProvider';
+import useSnackbar from '../useSnackbar';
 
 export default {
   component: Snackbar,
@@ -12,18 +15,23 @@ export default {
 
 type Story = StoryObj<typeof Snackbar>;
 
-const TIMEOUT = 10_000_000;
-
-function SnackbarStory({ text, action }: { text: string; action?: { label: string } }) {
-  const [timestamp, setTimestamp] = useState(0);
+function ShowOnMount(props: SnackbarCreationProps) {
+  const createSnackbar = useSnackbar();
 
   useEffect(() => {
-    // eslint-disable-next-line react-hooks/set-state-in-effect
-    setTimestamp(1);
+    createSnackbar(props);
+    // This visual fixture creates once per mount, not on every render of its props.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  return null;
+}
+
+function SnackbarStory({ text, action }: { text: string; action?: { label: string } }) {
   return (
-    <Snackbar text={<span>{text}</span>} timestamp={timestamp} timeout={TIMEOUT} action={action} />
+    <SnackbarProvider>
+      <ShowOnMount text={<span>{text}</span>} action={action} duration="indefinite" />
+    </SnackbarProvider>
   );
 }