@xsolla/xui-toast 0.158.0 → 0.159.0

package/README.md

@@ -1,6 +1,6 @@
 # Toast
 
-A cross-platform toast notification system built on a provider/context architecture with a hook-based API. Supports multiple variants, configurable position and alignment, custom durations, custom icons, and programmatic dismiss on both web and React Native.
+A cross-platform toast notification system matching the base Figma toast. Use it for short, non-blocking feedback with a title, optional description, optional action, and automatic or manual dismissal.
 
 ## Installation
 
@@ -19,11 +19,11 @@ import {
   useToast,
   type ToastProps,
   type ToastOptions,
-  type ToastVariant,
+  type ToastType,
   type ToastPosition,
   type ToastAlign,
   type UseToastReturn,
-} from '@xsolla/xui-toast';
+} from "@xsolla/xui-toast";
 ```
 
 ## Quick start
@@ -31,14 +31,16 @@ import {
 Wrap your app with `ToastProvider`, then call `useToast` from any descendant.
 
 ```tsx
-import * as React from 'react';
-import { XUIProvider } from '@xsolla/xui-core';
-import { ToastProvider, useToast } from '@xsolla/xui-toast';
+import * as React from "react";
+import { XUIProvider } from "@xsolla/xui-core";
+import { ToastProvider, useToast } from "@xsolla/xui-toast";
 
 function SaveButton() {
   const toast = useToast();
   return (
-    <button onClick={() => toast.success('Saved successfully')}>Save</button>
+    <button onClick={() => toast.success({ title: "Saved successfully" })}>
+      Save
+    </button>
   );
 }
 
@@ -61,26 +63,31 @@ export default function App() {
 
 Root provider. Manages toast state, auto-dismiss timers, and renders the `ToastGroup`.
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `children` | `ReactNode` | — | Application content. |
-| `position` | `"top" \| "bottom"` | `"top"` | Vertical anchor of the toast container. |
-| `align` | `"left" \| "center" \| "right"` | `"center"` | Horizontal alignment of toasts within the container. |
-| `defaultDuration` | `number` | `5000` | Default auto-dismiss duration in ms. Set `0` to disable auto-dismiss globally. |
-| `maxWidth` | `number` | — | Maximum width (px) of the toast stack. When unset, toasts stretch to the container width. |
+| Prop              | Type                            | Default    | Description                                                                                                   |
+| ----------------- | ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `testID`          | `string`                        | -          | Test ID for testing frameworks. On web this renders as `data-testid`; on React Native it renders as `testID`. |
+| `children`        | `ReactNode`                     | -          | Application content.                                                                                          |
+| `position`        | `"top" \| "bottom"`             | `"top"`    | Vertical anchor of the toast container.                                                                       |
+| `align`           | `"left" \| "center" \| "right"` | `"center"` | Horizontal alignment of toasts within the container.                                                          |
+| `defaultDuration` | `number`                        | `5000`     | Default auto-dismiss duration in ms. Set `0` to disable auto-dismiss globally.                                |
+| `maxWidth`        | `number`                        | -          | Maximum width in px of the toast stack.                                                                       |
 
 ### `<Toast>`
 
 The individual toast cell. Used internally by `ToastGroup`, but can be rendered standalone for static display.
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `id` | `string` | — | Required unique identifier. |
-| `message` | `string` | — | Required message text. |
-| `variant` | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Visual variant; determines the default icon and accent colour. |
-| `icon` | `ReactNode` | — | Custom icon. Overrides the default. |
-| `duration` | `number` | — | Auto-dismiss duration in ms. `0` or omitted = no auto-dismiss. |
-| `onClose` | `() => void` | — | Close handler. Required for the close button to render. |
+| Prop              | Type                                             | Default     | Description                                                        |
+| ----------------- | ------------------------------------------------ | ----------- | ------------------------------------------------------------------ |
+| `id`              | `string`                                         | -           | Required unique identifier.                                        |
+| `type`            | `"alert" \| "success" \| "neutral" \| "warning"` | `"neutral"` | Visual and accessibility type.                                     |
+| `title`           | `string`                                         | -           | Short primary text, ideally 1 to 5 words.                          |
+| `description`     | `string`                                         | -           | Optional supporting text.                                          |
+| `icon`            | `boolean \| ReactNode`                           | `true`      | Show the default icon, hide it with `false`, or pass a custom one. |
+| `action`          | `ReactElement`                                   | -           | Optional action element, typically a `FlexButton`.                 |
+| `showCloseButton` | `boolean`                                        | `true`      | Show the trailing dismiss control when `onClose` is provided.      |
+| `progress`        | `boolean`                                        | `false`     | Show the bottom progress strip.                                    |
+| `duration`        | `number`                                         | -           | Auto-dismiss duration in ms. `0` or omitted = no auto-dismiss.     |
+| `onClose`         | `() => void`                                     | -           | Close handler. Required for the close button to render.            |
 
 Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
@@ -88,13 +95,13 @@ Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
 Renders the stack of visible toasts. On web uses `ReactDOM.createPortal` to escape stacking contexts; on React Native uses absolute positioning.
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `toasts` | `ToastData[]` | — | Toasts to render. |
-| `position` | `"top" \| "bottom"` | `"top"` | Vertical anchor. |
-| `align` | `"left" \| "center" \| "right"` | `"center"` | Horizontal alignment. |
-| `maxWidth` | `number` | — | Maximum width (px). |
-| `onDismiss` | `(id: string) => void` | — | Dismiss callback per toast. |
+| Prop        | Type                            | Default    | Description                 |
+| ----------- | ------------------------------- | ---------- | --------------------------- |
+| `toasts`    | `ToastData[]`                   | -          | Toasts to render.           |
+| `position`  | `"top" \| "bottom"`             | `"top"`    | Vertical anchor.            |
+| `align`     | `"left" \| "center" \| "right"` | `"center"` | Horizontal alignment.       |
+| `maxWidth`  | `number`                        | -          | Maximum width in px.        |
+| `onDismiss` | `(id: string) => void`          | -          | Dismiss callback per toast. |
 
 Inherits `ThemeOverrideProps`.
 
@@ -102,87 +109,103 @@ Inherits `ThemeOverrideProps`.
 
 Hook that returns toast helpers. Throws if called outside a `ToastProvider`.
 
-| Method | Signature | Description |
-| --- | --- | --- |
-| `toast` | `(options: ToastOptions) => string` | Show a toast with full options. Returns the toast ID. |
-| `success` | `(message: string, options?) => string` | Show a success toast. |
-| `info` | `(message: string, options?) => string` | Show an info toast. |
-| `warning` | `(message: string, options?) => string` | Show a warning toast. |
-| `error` | `(message: string, options?) => string` | Show an error toast. |
-| `dismiss` | `(id: string) => void` | Dismiss a specific toast by ID. |
-| `dismissAll` | `() => void` | Dismiss all visible toasts. |
+| Method       | Signature                                         | Description                                           |
+| ------------ | ------------------------------------------------- | ----------------------------------------------------- |
+| `toast`      | `(options: ToastOptions) => string`               | Show a toast with full options. Returns the toast ID. |
+| `alert`      | `(options: Omit<ToastOptions, "type">) => string` | Show an alert toast.                                  |
+| `success`    | `(options: Omit<ToastOptions, "type">) => string` | Show a success toast.                                 |
+| `neutral`    | `(options: Omit<ToastOptions, "type">) => string` | Show a neutral toast.                                 |
+| `warning`    | `(options: Omit<ToastOptions, "type">) => string` | Show a warning toast.                                 |
+| `dismiss`    | `(id: string) => void`                            | Dismiss a specific toast by ID.                       |
+| `dismissAll` | `() => void`                                      | Dismiss all visible toasts.                           |
 
 ### `ToastOptions`
 
-| Property | Type | Default | Description |
-| --- | --- | --- | --- |
-| `message` | `string` | — | Required message text. |
-| `variant` | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Visual variant. |
-| `icon` | `ReactNode` | — | Custom icon. |
-| `duration` | `number` | provider's `defaultDuration` | Auto-dismiss duration. `0` keeps the toast until dismissed manually. |
+| Property          | Type                                             | Default                      | Description                                                        |
+| ----------------- | ------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------ |
+| `type`            | `"alert" \| "success" \| "neutral" \| "warning"` | `"neutral"`                  | Visual and accessibility type.                                     |
+| `title`           | `string`                                         | -                            | Short primary text.                                                |
+| `description`     | `string`                                         | -                            | Optional supporting text.                                          |
+| `icon`            | `boolean \| ReactNode`                           | `true`                       | Show, hide, or override the icon.                                  |
+| `action`          | `ReactElement`                                   | -                            | Optional action element.                                           |
+| `showCloseButton` | `boolean`                                        | `true`                       | Show the close button when the toast is dismissible.               |
+| `progress`        | `boolean`                                        | `false`                      | Show the bottom progress strip.                                    |
+| `duration`        | `number`                                         | provider's `defaultDuration` | Auto-dismiss duration. `0` keeps the toast until dismissed manually. |
 
 ### `ToastData`
 
 Internal shape exposed via `ToastContext.toasts`.
 
-| Property | Type | Description |
-| --- | --- | --- |
-| `id` | `string` | Unique identifier generated by the provider. |
-| `variant` | `ToastVariant` | Toast variant. |
-| `message` | `string` | Message text. |
-| `icon` | `ReactNode \| undefined` | Custom icon, if any. |
-| `duration` | `number \| undefined` | Auto-dismiss duration. |
+| Property      | Type        | Description                                  |
+| ------------- | ----------- | -------------------------------------------- |
+| `id`          | `string`    | Unique identifier generated by the provider. |
+| `type`        | `ToastType` | Toast type.                                  |
+| `title`       | `string`    | Primary text.                                |
+| `description` | `string`    | Supporting text.                             |
+| `duration`    | `number`    | Auto-dismiss duration.                       |
 
 ### `ToastContext`
 
 React context with `{ toasts, addToast, dismissToast, dismissAllToasts }`. Typically consumed via `useToast`; available for advanced use cases:
 
 ```tsx
-import { useContext } from 'react';
-import { ToastContext } from '@xsolla/xui-toast';
+import { useContext } from "react";
+import { ToastContext } from "@xsolla/xui-toast";
 
 function ActiveCount() {
   const ctx = useContext(ToastContext);
-  if (!ctx) throw new Error('Must be within ToastProvider');
+  if (!ctx) throw new Error("Must be within ToastProvider");
   return <span>Active toasts: {ctx.toasts.length}</span>;
 }
 ```
 
 ## Examples
 
-### Variants
+### Types
 
 ```tsx
-import * as React from 'react';
-import { useToast } from '@xsolla/xui-toast';
+import * as React from "react";
+import { useToast } from "@xsolla/xui-toast";
 
-export default function Variants() {
+export default function Types() {
   const toast = useToast();
   return (
-    <div style={{ display: 'flex', gap: 8 }}>
-      <button onClick={() => toast.success('Quest activated')}>Success</button>
-      <button onClick={() => toast.info('You received 50 points')}>Info</button>
-      <button onClick={() => toast.warning('Session about to expire')}>Warning</button>
-      <button onClick={() => toast.error('Failed to save')}>Error</button>
+    <div style={{ display: "flex", gap: 8 }}>
+      <button onClick={() => toast.neutral({ title: "Reward claimed" })}>
+        Neutral
+      </button>
+      <button onClick={() => toast.success({ title: "Quest activated" })}>
+        Success
+      </button>
+      <button onClick={() => toast.warning({ title: "Session expires soon" })}>
+        Warning
+      </button>
+      <button onClick={() => toast.alert({ title: "Connection lost" })}>
+        Alert
+      </button>
     </div>
   );
 }
 ```
 
-### Standalone Toast (no provider)
+### Standalone Toast With Action
 
 ```tsx
-import * as React from 'react';
-import { Toast } from '@xsolla/xui-toast';
+import * as React from "react";
+import { FlexButton } from "@xsolla/xui-button";
+import { Toast } from "@xsolla/xui-toast";
 
 export default function Standalone() {
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, maxWidth: 400 }}>
-      <Toast id="1" variant="success" message="Quest activated" onClose={() => {}} />
-      <Toast id="2" variant="info" message="You received 50 points" onClose={() => {}} />
-      <Toast id="3" variant="warning" message="Session about to expire" onClose={() => {}} />
-      <Toast id="4" variant="error" message="Failed to save" onClose={() => {}} />
-    </div>
+    <Toast
+      id="retry"
+      type="alert"
+      title="Connection lost"
+      description="Check your network and try again"
+      action={<FlexButton>Retry</FlexButton>}
+      progress
+      onClose={() => {}}
+    />
   );
 }
 ```
@@ -190,134 +213,69 @@ export default function Standalone() {
 ### Custom duration
 
 ```tsx
-import * as React from 'react';
-import { useToast } from '@xsolla/xui-toast';
+import * as React from "react";
+import { useToast } from "@xsolla/xui-toast";
 
 export default function Duration() {
-  const toast = useToast();
-  return (
-    <div style={{ display: 'flex', gap: 8 }}>
-      <button onClick={() => toast.toast({ message: 'Stays 10s', duration: 10000 })}>10s</button>
-      <button onClick={() => toast.toast({ message: 'Stays 2s', duration: 2000 })}>2s</button>
-      <button onClick={() => toast.toast({ message: 'Manual dismiss', duration: 0 })}>No auto-dismiss</button>
-    </div>
-  );
-}
-```
-
-### Custom icon
-
-```tsx
-import * as React from 'react';
-import { useToast } from '@xsolla/xui-toast';
-import { Star } from '@xsolla/xui-icons-base';
-
-export default function CustomIcon() {
   const toast = useToast();
   return (
     <button
       onClick={() =>
-        toast.toast({ message: 'You earned a gold star', variant: 'success', icon: <Star /> })
+        toast.toast({
+          type: "neutral",
+          title: "Manual dismiss",
+          duration: 0,
+        })
       }
     >
-      Show
+      Show sticky toast
     </button>
   );
 }
 ```
 
-### Programmatic dismiss
-
-```tsx
-import * as React from 'react';
-import { useToast } from '@xsolla/xui-toast';
-
-export default function Dismiss() {
-  const toast = useToast();
-  const [lastId, setLastId] = React.useState<string | null>(null);
-
-  return (
-    <div style={{ display: 'flex', gap: 8 }}>
-      <button onClick={() => setLastId(toast.info('New notification'))}>Show</button>
-      <button onClick={() => lastId && toast.dismiss(lastId)}>Dismiss last</button>
-      <button onClick={() => toast.dismissAll()}>Dismiss all</button>
-    </div>
-  );
-}
-```
-
 ### Position and alignment
 
 ```tsx
-import * as React from 'react';
-import { ToastProvider, useToast } from '@xsolla/xui-toast';
+import * as React from "react";
+import { ToastProvider, useToast } from "@xsolla/xui-toast";
 
 function Trigger() {
   const toast = useToast();
-  return <button onClick={() => toast.info('Bottom-right toast')}>Show</button>;
+  return (
+    <button onClick={() => toast.neutral({ title: "Bottom-right toast" })}>
+      Show
+    </button>
+  );
 }
 
 export default function BottomRight() {
   return (
-    <ToastProvider position="bottom" align="right" maxWidth={400}>
+    <ToastProvider position="bottom" align="right" maxWidth={440}>
       <Trigger />
     </ToastProvider>
   );
 }
 ```
 
-### React Native
-
-The `useToast` hook is identical on React Native; use `onPress` instead of `onClick`.
-
-```tsx
-import * as React from 'react';
-import { View } from 'react-native';
-import { Button } from '@xsolla/xui-button';
-import { XUIProvider } from '@xsolla/xui-core';
-import { ToastProvider, useToast } from '@xsolla/xui-toast';
-
-function Trigger() {
-  const toast = useToast();
-  return <Button onPress={() => toast.success('Saved')}>Save</Button>;
-}
-
-export default function App() {
-  return (
-    <XUIProvider initialMode="dark">
-      <ToastProvider position="top">
-        <View style={{ flex: 1 }}>
-          <Trigger />
-        </View>
-      </ToastProvider>
-    </XUIProvider>
-  );
-}
-```
-
 ## Platform support
 
-| Aspect | Web | React Native |
-| --- | --- | --- |
-| Rendering | `ReactDOM.createPortal` to `document.body` | Absolute-positioned `Box` in tree |
-| Event handlers | `onClick` | `onPress` |
-| Root container | Any element | Must have `flex: 1` |
+| Aspect         | Web                                        | React Native                      |
+| -------------- | ------------------------------------------ | --------------------------------- |
+| Rendering      | `ReactDOM.createPortal` to `document.body` | Absolute-positioned `Box` in tree |
+| Event handlers | `onClick`                                  | `onPress`                         |
+| Root container | Any element                                | Must have `flex: 1`               |
 
 ## Accessibility
 
-- Each toast renders with `role="alert"` and `aria-live="polite"` for assistive technology.
-- The close button has `aria-label="Dismiss toast"` and is keyboard-focusable.
-- Default icons are decorative.
-- Messages clamp to 2 lines for readability.
+- Neutral and success toasts render with `role="status"` and polite announcements.
+- Warning and alert toasts render with `role="alert"` and assertive announcements.
+- The close button has `aria-label="Dismiss notification"`.
+- Do not rely on color alone; the icon and text also communicate the type.
 
 ## Troubleshooting
 
-- **"useToast must be used within a ToastProvider"** — ensure the calling component is a descendant of `ToastProvider`.
-- **Toasts hidden on React Native** — wrap content in `<View style={{ flex: 1 }}>` inside `ToastProvider`.
-- **Toasts appear behind a modal (web)** — `ToastGroup` uses `z-index: 9999`. Place `ToastProvider` above the modal in the tree, or adjust z-index.
-- **Auto-dismiss not working** — `duration: 0` disables auto-dismiss; check both per-toast and provider defaults.
-
-## Related
-
-- [Notification](./notification.md) — declarative toast/inline notification.
-- [NotificationPanel](./notification-panel.md) — full-width inline banner.
+- **"useToast must be used within a ToastProvider"** - ensure the calling component is a descendant of `ToastProvider`.
+- **Toasts hidden on React Native** - wrap content in `<View style={{ flex: 1 }}>` inside `ToastProvider`.
+- **Toasts appear behind a modal (web)** - `ToastGroup` uses `z-index: 9999`. Place `ToastProvider` above the modal in the tree, or adjust z-index.
+- **Auto-dismiss not working** - `duration: 0` disables auto-dismiss; check both per-toast and provider defaults.

package/native/index.d.mts

@@ -1,29 +1,54 @@
 import * as React from 'react';
-import React__default, { ReactNode } from 'react';
+import React__default, { ReactNode, ReactElement } from 'react';
 import { ThemeOverrideProps } from '@xsolla/xui-core';
 
-type ToastVariant = "success" | "info" | "warning" | "error";
+type ToastType = "alert" | "success" | "neutral" | "warning";
 type ToastPosition = "top" | "bottom";
 type ToastAlign = "left" | "center" | "right";
 interface ToastData {
     id: string;
-    variant: ToastVariant;
-    message: string;
-    icon?: ReactNode;
+    type: ToastType;
+    title?: string;
+    description?: string;
+    icon?: boolean | ReactNode;
+    action?: ReactElement;
+    showCloseButton?: boolean;
+    progress?: boolean;
     duration?: number;
 }
+interface ToastColorScheme {
+    background: string;
+    text: string;
+    descriptionText: string;
+    divider: string;
+    actionText: string;
+    shadow?: string;
+    backdropFilter?: string;
+}
 interface ToastProps extends ThemeOverrideProps {
     id: string;
-    variant?: ToastVariant;
-    message: string;
-    icon?: ReactNode;
+    type?: ToastType;
+    title?: string;
+    description?: string;
+    icon?: boolean | ReactNode;
+    action?: ReactElement;
+    showCloseButton?: boolean;
+    progress?: boolean;
     duration?: number;
     onClose?: () => void;
+    /** Internal color override for product-specific toast surfaces */
+    colorScheme?: ToastColorScheme;
+    /** Test ID for testing frameworks */
+    testID?: string;
 }
 interface ToastOptions {
-    variant?: ToastVariant;
-    message: string;
-    icon?: ReactNode;
+    type?: ToastType;
+    title?: string;
+    description?: string;
+    icon?: boolean | ReactNode;
+    action?: ReactElement;
+    showCloseButton?: boolean;
+    progress?: boolean;
     duration?: number;
 }
 interface ToastGroupProps extends ThemeOverrideProps {
@@ -32,6 +57,8 @@ interface ToastGroupProps extends ThemeOverrideProps {
     align?: ToastAlign;
     maxWidth?: number;
     onDismiss: (id: string) => void;
+    /** Test ID for testing frameworks */
+    testID?: string;
 }
 interface ToastContextType {
     toasts: ToastData[];
@@ -45,11 +72,13 @@ interface ToastProviderProps {
     align?: ToastAlign;
     defaultDuration?: number;
     maxWidth?: number;
+    /** Test ID for testing frameworks */
+    testID?: string;
 }
 
 declare const Toast: React__default.FC<ToastProps>;
 
-declare const ToastGroup: React__default.MemoExoticComponent<({ toasts, position, align, maxWidth, onDismiss, themeMode, themeProductContext, }: ToastGroupProps) => React__default.ReactPortal | null>;
+declare const ToastGroup: React__default.MemoExoticComponent<({ toasts, position, align, maxWidth, onDismiss, testID, themeMode, themeProductContext, }: ToastGroupProps) => React__default.ReactPortal | null>;
 
 declare const ToastProvider: React__default.FC<ToastProviderProps>;
 
@@ -58,14 +87,14 @@ declare const ToastContext: React.Context<ToastContextType | null>;
 interface UseToastReturn {
     /** Show a toast with custom options */
     toast: (options: ToastOptions) => string;
+    /** Show an alert toast */
+    alert: (options: Omit<ToastOptions, "type">) => string;
     /** Show a success toast */
-    success: (message: string, options?: Omit<ToastOptions, "message" | "variant">) => string;
-    /** Show an info toast */
-    info: (message: string, options?: Omit<ToastOptions, "message" | "variant">) => string;
+    success: (options: Omit<ToastOptions, "type">) => string;
+    /** Show a neutral toast */
+    neutral: (options: Omit<ToastOptions, "type">) => string;
     /** Show a warning toast */
-    warning: (message: string, options?: Omit<ToastOptions, "message" | "variant">) => string;
-    /** Show an error toast */
-    error: (message: string, options?: Omit<ToastOptions, "message" | "variant">) => string;
+    warning: (options: Omit<ToastOptions, "type">) => string;
     /** Dismiss a specific toast by ID */
     dismiss: (id: string) => void;
     /** Dismiss all toasts */
@@ -73,4 +102,4 @@ interface UseToastReturn {
 }
 declare const useToast: () => UseToastReturn;
 
-export { Toast, type ToastAlign, ToastContext, type ToastContextType, type ToastData, ToastGroup, type ToastGroupProps, type ToastOptions, type ToastPosition, type ToastProps, ToastProvider, type ToastProviderProps, type ToastVariant, type UseToastReturn, useToast };
+export { Toast, type ToastAlign, type ToastColorScheme, ToastContext, type ToastContextType, type ToastData, ToastGroup, type ToastGroupProps, type ToastOptions, type ToastPosition, type ToastProps, ToastProvider, type ToastProviderProps, type ToastType, type UseToastReturn, useToast };