@transferwise/components 0.0.0-experimental-820ab92 → 0.0.0-experimental-6bb771e

package/build/types/Body/Body.d.ts

@@ -11,7 +11,7 @@ export type BodyProps = HTMLAttributes<HTMLSpanElement | HTMLParagraphElement> &
      */
     preserveNewlines?: boolean;
 };
-declare const Body: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement | HTMLParagraphElement> & {
+declare const Body: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement | HTMLSpanElement> & {
     /** @default 'body-default' */
     type?: BodyTypes;
     /** @default 'div' */
@@ -21,6 +21,6 @@ declare const Body: import("react").ForwardRefExoticComponent<HTMLAttributes<HTM
      * @default false
      */
     preserveNewlines?: boolean;
-} & import("react").RefAttributes<HTMLDivElement | HTMLSpanElement | HTMLParagraphElement | null>>;
+} & import("react").RefAttributes<HTMLDivElement | HTMLParagraphElement | HTMLSpanElement | null>>;
 export default Body;
 //# sourceMappingURL=Body.d.ts.map

package/build/types/IconButton/IconButton.d.ts

@@ -16,6 +16,6 @@ declare const IconButton: import("react").ForwardRefExoticComponent<{
     /** @default 'default' */
     type?: "default" | "negative";
     'data-testid'?: string;
-} & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "onClick" | "target" | "href"> & Pick<ButtonHTMLAttributes<HTMLButtonElement>, "disabled" | "onClick"> & Pick<HTMLAttributes<HTMLDivElement>, "children" | "className" | "id" | "tabIndex" | "role" | "aria-label"> & import("react").RefAttributes<unknown>>;
+} & Pick<AnchorHTMLAttributes<HTMLAnchorElement>, "onClick" | "target" | "href"> & Pick<ButtonHTMLAttributes<HTMLButtonElement>, "disabled" | "onClick"> & Pick<HTMLAttributes<HTMLDivElement>, "id" | "className" | "tabIndex" | "role" | "aria-label" | "children"> & import("react").RefAttributes<unknown>>;
 export default IconButton;
 //# sourceMappingURL=IconButton.d.ts.map

package/build/types/MoneyInput/MoneyInput.d.ts

@@ -55,6 +55,7 @@ declare const _default: import("react").FC<{
     selectProps?: Partial<SelectInputProps<CurrencyOptionItem>> | undefined;
     amount: number | null;
     searchPlaceholder?: string | undefined;
+    decimals?: number | undefined;
     currencies: readonly CurrencyItem[];
     selectedCurrency: CurrencyOptionItem;
     onCurrencyChange?: ((value: CurrencyOptionItem) => void) | undefined;
@@ -66,7 +67,6 @@ declare const _default: import("react").FC<{
     }) => void) | undefined;
     customActionLabel?: import("react").ReactNode;
     onCustomAction?: (() => void) | undefined;
-    decimals?: number | undefined;
 }>;
 export default _default;
 //# sourceMappingURL=MoneyInput.d.ts.map

package/build/types/MoneyInput/MoneyInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MoneyInput.d.ts","sourceRoot":"","sources":["../../../src/MoneyInput/MoneyInput.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,EAGL,SAAS,EACT,UAAU,EACV,SAAS,EAEV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAuB,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnF,OAAO,EAKL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAO/B,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAoDnE,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC,gBAAgB,EAAE,kBAAkB,CAAC;IACrC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAC1C,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,YAAY,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;IAC3F,iBAAiB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACpC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,kCAAkC,GAAG,eAAe,GAC9D,OAAO,CAAC,wBAAwB,CAAC,CAAC;;SA5B7B,MAAM;wBACS,MAAM;YAMnB,SAAS,GAAG,UAAU,GAAG,SAAS;kBAF3B,MAAM;iBAYP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;kBACrB,OAAO,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;YAZnD,MAAM,GAAG,IAAI;wBAID,MAAM;gBARd,SAAS,YAAY,EAAE;sBACjB,kBAAkB;wBACjB,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI;sBAIrC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI;;sBAM9B,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,YAAY,EAAE,CAAA;KAAE,KAAK,IAAI;;sBAEzE,MAAM,IAAI;eAQhB,MAAM;;AA0anB,wBAA2F"}
+{"version":3,"file":"MoneyInput.d.ts","sourceRoot":"","sources":["../../../src/MoneyInput/MoneyInput.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,EAGL,SAAS,EACT,UAAU,EACV,SAAS,EAEV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAuB,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnF,OAAO,EAKL,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAO/B,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAoDnE,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IACpC,gBAAgB,EAAE,kBAAkB,CAAC;IACrC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IAC1C,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,YAAY,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;IAC3F,iBAAiB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACpC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC5D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,kCAAkC,GAAG,eAAe,GAC9D,OAAO,CAAC,wBAAwB,CAAC,CAAC;;SA5B7B,MAAM;wBACS,MAAM;YAMnB,SAAS,GAAG,UAAU,GAAG,SAAS;kBAF3B,MAAM;iBAYP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;kBACrB,OAAO,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;YAZnD,MAAM,GAAG,IAAI;wBAID,MAAM;eAcf,MAAM;gBAtBL,SAAS,YAAY,EAAE;sBACjB,kBAAkB;wBACjB,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI;sBAIrC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI;;sBAM9B,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,YAAY,EAAE,CAAA;KAAE,KAAK,IAAI;;sBAEzE,MAAM,IAAI;;AAkb7B,wBAA2F"}

package/build/types/Title/Title.d.ts

@@ -10,7 +10,7 @@ export type TitleProps = LabelHTMLAttributes<HTMLHeadingElement | HTMLSpanElemen
      */
     type?: TitleTypes;
 };
-declare const Title: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLSpanElement | HTMLHeadingElement | HTMLLabelElement> & React.LiHTMLAttributes<HTMLLIElement> & {
+declare const Title: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLHeadingElement | HTMLLabelElement | HTMLSpanElement> & React.LiHTMLAttributes<HTMLLIElement> & {
     /**
      * Default value will based one `type` prop
      */
@@ -19,6 +19,6 @@ declare const Title: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<H
      * Default value: {@link DEFAULT_TYPE}
      */
     type?: TitleTypes;
-} & React.RefAttributes<HTMLSpanElement | HTMLHeadingElement | HTMLLabelElement | HTMLLegendElement | HTMLLIElement>>;
+} & React.RefAttributes<HTMLHeadingElement | HTMLLabelElement | HTMLLegendElement | HTMLLIElement | HTMLSpanElement>>;
 export default Title;
 //# sourceMappingURL=Title.d.ts.map

package/build/types/Upload/Steps/UploadImageStep/UploadImageStep.d.ts

@@ -15,7 +15,7 @@ export default class UploadImageStep extends PureComponent<UploadImageStepProps>
     uploadInputRef: import("react").RefObject<HTMLInputElement>;
     onManualUpload: () => void;
     onKeyDown: (event: React.KeyboardEvent<HTMLLabelElement>) => void;
-    getImage: () => number | true | import("react").JSX.Element | Iterable<import("react").ReactNode>;
+    getImage: () => number | true | Iterable<import("react").ReactNode> | import("react").JSX.Element;
     render(): import("react").JSX.Element;
 }
 //# sourceMappingURL=UploadImageStep.d.ts.map

package/build/types/UploadInput/UploadItem/UploadItemLink.d.ts

@@ -5,5 +5,5 @@ export declare const UploadItemLink: import("react").ForwardRefExoticComponent<{
     singleFileUpload: boolean;
 } & {
     children?: import("react").ReactNode | undefined;
-} & import("react").RefAttributes<HTMLDivElement | HTMLAnchorElement>>;
+} & import("react").RefAttributes<HTMLAnchorElement | HTMLDivElement>>;
 //# sourceMappingURL=UploadItemLink.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transferwise/components",
-  "version": "0.0.0-experimental-820ab92",
+  "version": "0.0.0-experimental-6bb771e",
   "description": "Neptune React components",
   "license": "Apache-2.0",
   "repository": {

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

@@ -0,0 +1,73 @@
+import { Meta, Source } from '@storybook/addon-docs/blocks';
+
+<Meta title="Prompts/Snackbar/Accessibility" />
+
+# Accessibility
+
+Snackbar is a polite live region. It uses `role="status"` and `aria-live="polite"`, so its message
+is announced when the screen reader is idle without interrupting the current task. It does not move
+keyboard focus when it appears.
+
+Visual sentiment and announcement urgency are separate. A negative Snackbar remains polite; use a
+different component when an update is urgent enough to interrupt the user.
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Transfer failed',
+  sentiment: 'negative',
+});`}
+/>
+
+## Actions and dismissal
+
+The optional action uses its visible label as its accessible name. Keep the label concise and make
+the outcome clear. Timed Snackbars pause while the pointer is hovering over them or while keyboard
+focus is inside.
+
+The polite announcement tells screen-reader users that pressing `Escape` dismisses the Snackbar
+without moving focus. On desktop, the close button also has an accessible name and dismisses through
+the normal exit motion. On mobile, the Snackbar can be dismissed with a downward swipe. A swipe
+below 50% of its rendered height, an upward or horizontal gesture, or a cancelled gesture returns it
+to its resting position.
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Transfer deleted',
+  action: {
+    label: 'Undo',
+    onClick: handleUndo,
+  },
+  duration: 'extended',
+  onDismiss: handleDismiss,
+});`}
+/>
+
+## Media
+
+Default sentiment media already includes the appropriate accessible treatment. If custom media
+conveys meaning, add its accessibility attributes directly to the element you pass. Decorative
+custom media should be hidden from assistive technology.
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Added to your wallet',
+  media: <Card title="Card" />,
+});`}
+/>
+
+<Source
+  dark
+  code={`showSnackbar({
+  text: 'Offer applied',
+  media: <GiftBox aria-hidden />,
+});`}
+/>
+
+## Motion and zoom
+
+Snackbar removes movement and scaling when `prefers-reduced-motion: reduce` is enabled. Its content
+reflows at high zoom and narrow viewport widths without horizontal scrolling. Keep messages short
+and plain so they remain easy to read when text wraps.

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

@@ -1,89 +1,473 @@
 import type { Meta, StoryObj } from '@storybook/react-webpack5';
-import { fn, userEvent, within } from 'storybook/test';
+import { fn } from 'storybook/test';
+import { Card } from '@transferwise/icons';
 
-import { wait } from '../../test-utils/wait';
 import {
   createSandboxStory,
   globalScope,
 } from '../../../.storybook/components/sandbox/SandboxEditor';
 import Button from '../../Button';
-import { Snackbar } from '../Snackbar';
+import { Snackbar, type SnackbarProps } from '../Snackbar';
 import { SnackbarConsumer } from '../SnackbarContext';
 import SnackbarProvider from '../SnackbarProvider';
 
-const meta: Meta = {
-  component: Snackbar,
+const SENTIMENTS = ['neutral', 'negative', 'warning', 'success', 'proposition'] as const;
+const DURATIONS = ['default', 'extended', 'indefinite'] as const;
+
+const meta = {
   title: 'Prompts/Snackbar',
-};
+  component: Snackbar,
+  parameters: {
+    docs: {
+      toc: true,
+      description: {
+        component:
+          'Snackbar is a brief, temporary notification that confirms the outcome of an action or process that has just happened. Keep its message short and plain: it supports one optional action, but no inline links or rich-text formatting. `Snackbar` can be rendered directly; use `SnackbarProvider` with `useSnackbar()` for app-level transient feedback.',
+      },
+    },
+  },
+  args: {
+    duration: 'default',
+    loading: false,
+    sentiment: 'neutral',
+    text: 'Changes saved',
+  },
+  argTypes: {
+    text: {
+      control: 'text',
+      description: 'Short, plain-text Snackbar message.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    sentiment: {
+      control: 'radio',
+      options: SENTIMENTS,
+      description: 'Controls the colour scheme and sentiment-derived default media.',
+      table: {
+        defaultValue: { summary: 'neutral' },
+        type: { summary: 'Sentiment' },
+      },
+    },
+    media: {
+      control: false,
+      description:
+        'Overrides the sentiment-derived media. Custom media is displayed in the 24×24px media slot and should provide its own accessibility attributes when meaningful.',
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    loading: {
+      control: 'boolean',
+      description:
+        'Replaces the media with a ProcessIndicator, uses neutral styling, and prevents automatic dismissal.',
+      table: {
+        defaultValue: { summary: 'false' },
+        type: { summary: 'boolean' },
+      },
+    },
+    action: {
+      control: false,
+      description:
+        'One optional small Button. Supports a callback action or navigation through href and target.',
+      table: {
+        type: {
+          summary: 'SnackbarAction',
+          detail:
+            "Pick<ButtonProps, 'onClick' | 'href' | 'target'> & { label: ButtonProps['children'] }",
+        },
+      },
+    },
+    duration: {
+      control: 'inline-radio',
+      options: DURATIONS,
+      description: 'Controls automatic dismissal using the design-defined duration presets.',
+      table: {
+        defaultValue: { summary: 'default' },
+        type: { summary: "'default' | 'extended' | 'indefinite'" },
+      },
+    },
+    onDismiss: {
+      control: false,
+      description: 'Called after the Snackbar completes its exit transition.',
+      table: {
+        type: { summary: '() => void' },
+      },
+    },
+    timeout: {
+      table: { disable: true },
+    },
+    theme: {
+      table: { disable: true },
+    },
+  },
+} satisfies Meta<SnackbarProps>;
+
 export default meta;
+type Story = StoryObj<typeof meta>;
+
+type PreviewStoryArgs = SnackbarProps & {
+  previewAction: boolean;
+  previewMedia: 'default' | 'custom';
+  previewOnDismiss: boolean;
+};
+
+type SnackbarExample = {
+  label: string;
+  props: SnackbarProps;
+};
+
+const previewArgGroup = {
+  category: 'Storybook Preview options',
+  type: { summary: undefined },
+};
+
+const previewArgTypes = {
+  previewAction: {
+    name: 'Preview with `action`',
+    control: 'boolean',
+    table: previewArgGroup,
+  },
+  previewMedia: {
+    name: 'Preview with `media`',
+    control: 'radio',
+    options: ['default', 'custom'],
+    table: previewArgGroup,
+  },
+  previewOnDismiss: {
+    name: 'Preview with `onDismiss`',
+    control: 'boolean',
+    table: previewArgGroup,
+  },
+} as const;
+
+const SnackbarExamples = ({ examples }: { examples: SnackbarExample[] }) => (
+  <SnackbarProvider>
+    <SnackbarConsumer>
+      {({ createSnackbar }) => (
+        <div
+          style={{
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: 'var(--size-8)',
+          }}
+        >
+          {examples.map(({ label, props }) => (
+            <Button key={label} v2 size="md" onClick={() => createSnackbar(props)}>
+              {label}
+            </Button>
+          ))}
+        </div>
+      )}
+    </SnackbarConsumer>
+  </SnackbarProvider>
+);
+
+/**
+ * Use the controls to preview the public Snackbar properties. Rich values such as `action`,
+ * `media`, and `onDismiss` use dedicated preview controls because Storybook cannot edit React
+ * elements or callback functions directly.
+ */
+export const Playground: StoryObj<PreviewStoryArgs> = {
+  args: {
+    duration: 'default',
+    previewAction: true,
+    previewMedia: 'default',
+    previewOnDismiss: true,
+    loading: false,
+  },
+  argTypes: previewArgTypes,
+  render: ({ previewAction, previewMedia, previewOnDismiss, ...props }) => (
+    <SnackbarExamples
+      examples={[
+        {
+          label: 'Show Snackbar',
+          props: {
+            ...props,
+            action: previewAction ? { label: 'View', onClick: fn() } : undefined,
+            media: previewMedia === 'custom' ? <Card title="Card" /> : undefined,
+            onDismiss: previewOnDismiss ? fn() : undefined,
+          },
+        },
+      ]}
+    />
+  ),
+};
 
 export const Sandbox = createSandboxStory({
-  code: `<SnackbarProvider>
-  <SnackbarConsumer>
-    {({ createSnackbar }) => (
-      <Button v2 size="md"
-        onClick={() =>
-          createSnackbar({
-            text: <span>Transfer completed successfully</span>,
-            action: {
-              label: 'View',
-              onClick: () => console.log('View clicked'),
-            },
-          })
-        }
-      >
-        Show Snackbar
-      </Button>
-    )}
-  </SnackbarConsumer>
-</SnackbarProvider>`,
+  code: `const SnackbarTrigger = () => {
+  const showSnackbar = useSnackbar();
+
+  return (
+    <Button
+      v2
+      size="md"
+      onClick={() =>
+        showSnackbar({
+          text: 'Transfer completed successfully',
+          sentiment: 'success',
+          action: {
+            label: 'View',
+            onClick: () => console.log('View clicked'),
+          },
+          duration: 'extended',
+        })
+      }
+    >
+      Show Snackbar
+    </Button>
+  );
+};
+
+const App = () => (
+  <SnackbarProvider>
+    <SnackbarTrigger />
+  </SnackbarProvider>
+);`,
   scope: globalScope,
 });
 
-export const Basic: StoryObj = {
+/**
+ * `Snackbar` remains available for direct rendering. For app-level feedback, wrap the relevant
+ * app boundary in `SnackbarProvider`, then call the function returned by `useSnackbar()` after an
+ * action or process completes. The Provider owns mounting, timers, replacement, and
+ * exit-before-enter behaviour.
+ *
+ * Keep the message short and plain. Snackbar copy does not support inline links or bold text.
+ */
+export const Basic: Story = {
+  args: {
+    duration: 'indefinite',
+    sentiment: 'success',
+    text: 'Changes saved',
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `// Direct rendering
+<Snackbar text="Changes saved" sentiment="success" />;
+
+// Programmatic app-level feedback
+const showSnackbar = useSnackbar();
+
+showSnackbar({
+  text: 'Changes saved',
+  sentiment: 'success',
+});`,
+      },
+    },
+  },
+  render: (args) => <SnackbarExamples examples={[{ label: 'Show Snackbar', props: args }]} />,
+};
+
+/**
+ * Use `sentiment` to match the meaning of the feedback. Sentiment controls appearance and default
+ * media; it does not change the polite screen-reader announcement.
+ *
+ * - `neutral`: general confirmation or information
+ * - `negative`: failed or unsuccessful outcome
+ * - `warning`: outcome that needs attention
+ * - `success`: successful completion
+ * - `proposition`: a relevant product proposition or benefit
+ */
+export const Sentiments: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `showSnackbar({ text: 'Details updated', sentiment: 'neutral' });
+showSnackbar({ text: 'Transfer failed', sentiment: 'negative' });
+showSnackbar({ text: 'Check the recipient details', sentiment: 'warning' });
+showSnackbar({ text: 'Transfer completed', sentiment: 'success' });
+showSnackbar({ text: 'You can earn a referral reward', sentiment: 'proposition' });`,
+      },
+    },
+  },
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        { label: 'Neutral', props: { text: 'Details updated', sentiment: 'neutral' } },
+        { label: 'Negative', props: { text: 'Transfer failed', sentiment: 'negative' } },
+        {
+          label: 'Warning',
+          props: { text: 'Check the recipient details', sentiment: 'warning' },
+        },
+        { label: 'Success', props: { text: 'Transfer completed', sentiment: 'success' } },
+        {
+          label: 'Proposition',
+          props: { text: 'You can earn a referral reward', sentiment: 'proposition' },
+        },
+      ]}
+    />
+  ),
+};
+
+/**
+ * Snackbar supports one optional small action. Use `onClick` for an in-place action or `href` for
+ * navigation. An action dismisses the Snackbar, so use `duration="extended"` when people need
+ * enough time to read and act.
+ */
+export const Actions: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `showSnackbar({
+  text: 'Transfer deleted',
+  action: {
+    label: 'Undo',
+    onClick: handleUndo,
+  },
+  duration: 'extended',
+});
+
+showSnackbar({
+  text: 'Your transfer is ready',
+  action: {
+    label: 'View transfer',
+    href: '/transfers/123',
+  },
+  duration: 'extended',
+});`,
+      },
+    },
+  },
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        {
+          label: 'Callback action',
+          props: {
+            text: 'Transfer deleted',
+            action: { label: 'Undo', onClick: fn() },
+            duration: 'extended',
+          },
+        },
+        {
+          label: 'Navigation action',
+          props: {
+            text: 'Your transfer is ready',
+            action: { label: 'View transfer', href: '/transfers/123' },
+            duration: 'extended',
+          },
+        },
+      ]}
+    />
+  ),
+};
+
+/**
+ * Default media is derived from `sentiment`. Use `media` only when a custom icon communicates the
+ * message more clearly. `loading` has the highest priority: it replaces default or custom media
+ * with a ProcessIndicator, switches to neutral styling, and remains visible indefinitely.
+ */
+export const MediaAndLoading: Story = {
   parameters: {
     docs: {
       source: {
-        type: 'code',
-        transform: async (src = '') => {
-          const match = /(function Render\(\).*?)(,\s+play:\s+async)/s.exec(src);
-          return match?.[1] || src;
+        code: `// Sentiment-derived default media
+showSnackbar({ text: 'Transfer completed', sentiment: 'success' });
+
+// Custom media
+showSnackbar({
+  text: 'Added to your wallet',
+  sentiment: 'success',
+  media: <Card title="Card" />,
+});
+
+// Loading takes precedence over media and duration
+showSnackbar({
+  text: 'Uploading document',
+  loading: true,
+});`,
+      },
+    },
+  },
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        {
+          label: 'Default media',
+          props: { text: 'Transfer completed', sentiment: 'success', duration: 'indefinite' },
+        },
+        {
+          label: 'Custom media',
+          props: {
+            text: 'Added to your wallet',
+            sentiment: 'success',
+            media: <Card title="Card" />,
+            duration: 'indefinite',
+          },
         },
+        {
+          label: 'Loading',
+          props: { text: 'Uploading document', loading: true },
+        },
+      ]}
+    />
+  ),
+};
+
+/**
+ * Duration is semantic rather than accepting arbitrary milliseconds:
+ *
+ * - `default`: 4 seconds for short confirmation without an action
+ * - `extended`: 6 seconds for additional reading or an action
+ * - `indefinite`: no automatic dismissal
+ *
+ * Timed Snackbars pause while hovered or while keyboard focus is inside, then resume when the
+ * interaction ends. Loading Snackbars are always indefinite.
+ *
+ * The deprecated millisecond `timeout` remains supported during migration but is not available in
+ * Storybook controls. Migrate values from 0–5000ms to `default`, values above 5000ms to `extended`,
+ * and intentionally persistent usage to `indefinite`. Semantic `duration` takes precedence when
+ * both are provided.
+ */
+export const Durations: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `showSnackbar({ text: 'Changes saved', duration: 'default' });
+showSnackbar({ text: 'Transfer deleted', duration: 'extended' });
+showSnackbar({ text: 'Uploading document', duration: 'indefinite' });`,
       },
     },
-    source: {
-      type: 'code',
-    },
-  },
-  render: function Render() {
-    return (
-      <SnackbarProvider>
-        <SnackbarConsumer>
-          {({ createSnackbar }) => {
-            return (
-              <Button
-                block
-                onClick={() => {
-                  createSnackbar({
-                    action: {
-                      label: 'View',
-                      onClick: fn(),
-                    },
-                    text: <span>Some text</span>,
-                  });
-                }}
-              >
-                Show Snackbar
-              </Button>
-            );
-          }}
-        </SnackbarConsumer>
-      </SnackbarProvider>
-    );
   },
-  play: async ({ canvasElement }) => {
-    await wait(0);
-    const canvas = within(canvasElement);
-    await userEvent.click(canvas.getByRole('button'));
+  render: () => (
+    <SnackbarExamples
+      examples={[
+        { label: 'Default · 4s', props: { text: 'Changes saved', duration: 'default' } },
+        { label: 'Extended · 6s', props: { text: 'Transfer deleted', duration: 'extended' } },
+        {
+          label: 'Indefinite',
+          props: { text: 'Uploading document', duration: 'indefinite' },
+        },
+      ]}
+    />
+  ),
+};
+
+/**
+ * Snackbars dismiss after their duration, after their action is used, through the desktop close
+ * button, or with a downward swipe on mobile. A mobile swipe must reach 50% of the rendered
+ * Snackbar height; shorter or cancelled swipes return it to its resting position.
+ *
+ * `onDismiss` runs after the exit transition completes, regardless of how dismissal started.
+ */
+export const Dismissal: Story = {
+  args: {
+    duration: 'indefinite',
+    onDismiss: fn(),
+    text: 'Swipe down or use the close button',
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `showSnackbar({
+  text: 'Changes saved',
+  duration: 'indefinite',
+  onDismiss: handleDismiss,
+});`,
+      },
+    },
   },
+  render: (args) => <SnackbarExamples examples={[{ label: 'Show Snackbar', props: args }]} />,
 };