@xsolla/xui-toast 0.120.0 → 0.121.0

package/README.md

@@ -1,37 +1,66 @@
 # Toast
 
-A cross-platform React toast notification system for displaying brief, auto-dismissing messages. Includes a provider, hook API, and support for multiple toast variants.
+A cross-platform React toast notification system for displaying brief, auto-dismissing messages. Built on a provider/context architecture with a hook-based API, the Toast package supports multiple variants, configurable positioning, custom durations, custom icons, and programmatic dismiss — on both React (web) and React Native.
 
 ## Installation
 
 ```bash
-npm install @xsolla/xui-toast
+npm install @xsolla/xui-toast @xsolla/xui-core
 # or
-yarn add @xsolla/xui-toast
+yarn add @xsolla/xui-toast @xsolla/xui-core
 ```
 
-## Demo
+**Peer dependencies:** `react >= 16.8.0`, `styled-components >= 4`
+
+## Architecture
+
+The toast system uses a **Provider → Context → Hook** pattern:
+
+```
+┌─────────────────────────────────────────────────┐
+│  ToastProvider                                   │
+│  ┌────────────┐  ┌───────────────────────────┐  │
+│  │ ToastContext│  │ ToastGroup (portal / abs) │  │
+│  │  - toasts  │  │  ┌───────┐ ┌───────┐      │  │
+│  │  - addToast│──▶  │ Toast │ │ Toast │ ...  │  │
+│  │  - dismiss │  │  └───────┘ └───────┘      │  │
+│  └────────────┘  └───────────────────────────┘  │
+│        ▲                                         │
+│        │  useToast()                             │
+│  ┌─────┴──────┐                                  │
+│  │  Your App  │                                  │
+│  └────────────┘                                  │
+└─────────────────────────────────────────────────┘
+```
 
-### Basic Setup (React Web)
+1. **`ToastProvider`** — Wraps your application. Manages toast state (an array of `ToastData`), auto-dismiss timers, and renders the `ToastGroup` container.
+2. **`ToastContext`** — React context that exposes `addToast`, `dismissToast`, and `dismissAllToasts` to descendants.
+3. **`useToast`** — Consumer hook that provides convenience methods (`success`, `info`, `warning`, `error`, `dismiss`, `dismissAll`).
+4. **`ToastGroup`** — Renders the stack of visible toasts. On web, uses `ReactDOM.createPortal` to escape z-index stacking contexts. On React Native, uses absolute positioning.
+5. **`Toast`** — The individual notification component with icon, message, and optional close button.
 
-Wrap your application with `ToastProvider`:
+## Quick Start
+
+### 1. Wrap your app with `ToastProvider`
+
+**React (Web):**
 
 ```tsx
-import * as React from 'react';
+import { XUIProvider } from '@xsolla/xui-core';
 import { ToastProvider } from '@xsolla/xui-toast';
 
 export default function App() {
   return (
-    <ToastProvider>
-      <YourApp />
-    </ToastProvider>
+    <XUIProvider initialMode="dark" initialProductContext="b2b">
+      <ToastProvider>
+        <YourApp />
+      </ToastProvider>
+    </XUIProvider>
   );
 }
 ```
 
-### Basic Setup (React Native)
-
-For React Native, wrap your app entry point with both `XUIProvider` and `ToastProvider`:
+**React Native:**
 
 ```tsx
 import React from 'react';
@@ -55,12 +84,34 @@ export default function App() {
 
 > **Important for React Native:** The `ToastProvider` renders toasts using absolute positioning. Ensure your app's root container has `flex: 1` so toasts position correctly relative to the screen.
 
-### Showing Toasts (React Web)
+### 2. Show toasts with `useToast`
+
+```tsx
+import { useToast } from '@xsolla/xui-toast';
+
+function SaveButton() {
+  const toast = useToast();
+
+  const handleSave = async () => {
+    try {
+      await saveData();
+      toast.success('Changes saved successfully');
+    } catch {
+      toast.error('Failed to save changes');
+    }
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+## Demo
+
+### Showing Toast Variants
 
-Use the `useToast` hook to show toasts:
+Each variant conveys a different semantic meaning and displays a corresponding icon:
 
 ```tsx
-import * as React from 'react';
 import { useToast } from '@xsolla/xui-toast';
 
 export default function ToastExample() {
@@ -117,10 +168,11 @@ export default function ToastExample() {
 }
 ```
 
-### Toast Variants
+### Toast Variants (Standalone `Toast` Component)
+
+The `Toast` component can be used standalone outside the provider for static display or custom layouts:
 
 ```tsx
-import * as React from 'react';
 import { Toast } from '@xsolla/xui-toast';
 
 export default function ToastVariants() {
@@ -137,8 +189,9 @@ export default function ToastVariants() {
 
 ### Custom Duration
 
+Control how long toasts remain visible. The default is 5000ms. Set `duration: 0` to disable auto-dismiss entirely:
+
 ```tsx
-import * as React from 'react';
 import { useToast } from '@xsolla/xui-toast';
 
 export default function CustomDuration() {
@@ -160,7 +213,44 @@ export default function CustomDuration() {
 }
 ```
 
-### Dismissing Toasts
+You can also set a global default duration on the provider:
+
+```tsx
+<ToastProvider defaultDuration={3000}>
+  <App />
+</ToastProvider>
+```
+
+### Custom Icons
+
+Override the default variant icon by passing a `ReactNode` via the `icon` option:
+
+```tsx
+import { useToast } from '@xsolla/xui-toast';
+import { Star } from '@xsolla/xui-icons';
+
+function CustomIconExample() {
+  const toast = useToast();
+
+  return (
+    <button
+      onClick={() =>
+        toast.toast({
+          message: 'You earned a gold star!',
+          variant: 'success',
+          icon: <Star />,
+        })
+      }
+    >
+      Show Custom Icon Toast
+    </button>
+  );
+}
+```
+
+### Dismissing Toasts Programmatically
+
+Every `toast.*()` call returns a unique ID. Use it to dismiss a specific toast:
 
 ```tsx
 import * as React from 'react';
@@ -189,8 +279,9 @@ export default function DismissExample() {
 
 ### Position Configuration
 
+Toasts can be anchored to the top or bottom of the viewport:
+
 ```tsx
-import * as React from 'react';
 import { ToastProvider, useToast } from '@xsolla/xui-toast';
 
 function ToastTrigger() {
@@ -207,109 +298,176 @@ export default function BottomPosition() {
 }
 ```
 
+### Multiple Toasts
+
+Multiple toasts stack vertically in the order they are created:
+
+```tsx
+import { useToast } from '@xsolla/xui-toast';
+
+function MultipleToastsExample() {
+  const toast = useToast();
+
+  const showMultiple = () => {
+    toast.success('First toast - Success');
+    setTimeout(() => toast.info('Second toast - Info'), 200);
+    setTimeout(() => toast.warning('Third toast - Warning'), 400);
+  };
+
+  return <button onClick={showMultiple}>Show Multiple Toasts</button>;
+}
+```
+
 ## API Reference
 
 ### ToastProvider
 
 The root provider component that manages toast state and renders the toast container.
 
-**ToastProvider Props:**
-
 | Prop | Type | Default | Description |
 | :--- | :--- | :------ | :---------- |
-| children | `ReactNode` | - | Application content. |
-| position | `"top" \| "bottom"` | `"top"` | Position of the toast container. |
-| defaultDuration | `number` | `5000` | Default auto-dismiss duration in milliseconds. |
+| `children` | `ReactNode` | — | Application content. |
+| `position` | `"top" \| "bottom"` | `"top"` | Position of the toast container on screen. |
+| `defaultDuration` | `number` | `5000` | Default auto-dismiss duration in milliseconds. Set to `0` to disable auto-dismiss globally. |
 
 ### useToast
 
-A hook that provides methods to show and dismiss toasts. Must be used within a `ToastProvider`.
+A hook that returns methods to show and dismiss toasts. Must be called within a `ToastProvider` — throws an error otherwise.
 
-**useToast Return Value:**
+**Return type: `UseToastReturn`**
 
 | Method | Signature | Description |
 | :----- | :-------- | :---------- |
-| toast | `(options: ToastOptions) => string` | Show a toast with custom 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 toasts. |
+| `toast` | `(options: ToastOptions) => string` | Show a toast with full control over options. Returns the toast ID. |
+| `success` | `(message: string, options?) => string` | Show a success toast with a check icon. |
+| `info` | `(message: string, options?) => string` | Show an info toast with an info icon. |
+| `warning` | `(message: string, options?) => string` | Show a warning toast with an alert icon. |
+| `error` | `(message: string, options?) => string` | Show an error toast with an alert icon. |
+| `dismiss` | `(id: string) => void` | Dismiss a specific toast by its ID. |
+| `dismissAll` | `() => void` | Dismiss all visible toasts at once. |
 
 ### Toast
 
-The individual toast component. Typically used internally by `ToastProvider`, but can be used standalone.
-
-**Toast Props:**
+The individual toast notification component. Used internally by `ToastGroup`, but can be rendered standalone for static display.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :------ | :---------- |
-| id | `string` | - | Unique toast identifier. |
-| message | `string` | - | Toast message text. |
-| variant | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Toast variant/style. |
-| icon | `ReactNode` | - | Custom icon (optional, uses default icons per variant). |
-| onClose | `() => void` | - | Callback when close button is clicked. If not provided, close button is hidden. |
+| `id` | `string` | — | Unique identifier for the toast (required). |
+| `message` | `string` | — | Toast message text (required). |
+| `variant` | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Visual variant that determines the icon color. |
+| `icon` | `ReactNode` | — | Custom icon element. When omitted, a default icon for the variant is used. |
+| `onClose` | `() => void` | — | Callback fired when the close button is clicked. If omitted, the close button is hidden. |
 
 ### ToastOptions
 
-Options passed to the `toast()` method.
+Options object passed to the `toast()` method or as the second argument to shorthand methods.
 
 | Property | Type | Default | Description |
 | :------- | :--- | :------ | :---------- |
-| message | `string` | - | Toast message text. |
-| variant | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Toast variant. |
-| icon | `ReactNode` | - | Custom icon. |
-| duration | `number` | Provider's `defaultDuration` | Auto-dismiss duration. Use `0` to disable auto-dismiss. |
+| `message` | `string` | — | Toast message text (required). |
+| `variant` | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Toast variant. |
+| `icon` | `ReactNode` | — | Custom icon element. |
+| `duration` | `number` | Provider's `defaultDuration` | Auto-dismiss duration in ms. Use `0` to keep the toast until manually dismissed. |
+
+### ToastData
+
+Internal data structure for a toast instance (available via `ToastContext`).
+
+| Property | Type | Description |
+| :------- | :--- | :---------- |
+| `id` | `string` | Unique identifier generated by the provider. |
+| `variant` | `ToastVariant` | The toast variant. |
+| `message` | `string` | Toast message text. |
+| `icon` | `ReactNode \| undefined` | Custom icon, if provided. |
+| `duration` | `number \| undefined` | Auto-dismiss duration. |
+
+### ToastContext
+
+The React context object. Typically consumed via `useToast`, but available for advanced use cases:
+
+```tsx
+import { useContext } from 'react';
+import { ToastContext } from '@xsolla/xui-toast';
 
-### Variant Values
+function CustomToastConsumer() {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('Must be within ToastProvider');
 
-| Variant | Use Case | Default Icon |
-| :------ | :------- | :----------- |
-| `success` | Positive outcomes, confirmations | Check circle |
-| `info` | General information, neutral messages | Info circle |
-| `warning` | Caution, requires attention | Alert circle |
-| `error` | Errors, failures, critical issues | Alert circle |
+  return <span>Active toasts: {ctx.toasts.length}</span>;
+}
+```
+
+### Variant Reference
+
+| Variant | Use Case | Default Icon | Icon Color Theme Path |
+| :------ | :------- | :----------- | :-------------------- |
+| `success` | Positive outcomes, confirmations | `<Check />` | `theme.colors.content.success.primary` |
+| `info` | General information, neutral messages | `<AlertCircle />` | `theme.colors.content.inverse` |
+| `warning` | Caution, requires user attention | `<AlertCircle />` | `theme.colors.content.warning.primary` |
+| `error` | Errors, failures, critical issues | `<AlertCircle />` | `theme.colors.content.alert.primary` |
 
 ## Theming
 
-Toast uses the inverse color scheme (dark background with light text):
+Toast uses the **inverse** color scheme (dark background with light text) to stand out from the application content:
+
+### Colors
 
 ```typescript
-// Toast styling accessed via theme
-theme.colors.background.inverse  // Toast background (black)
-theme.colors.content.inverse     // Toast text (white)
-
-// Variant-specific icon colors
-theme.colors.content.success.primary  // Success icon
-theme.colors.content.warning.primary  // Warning icon
-theme.colors.content.alert.primary    // Error icon
+theme.colors.background.inverse     // Toast background
+theme.colors.content.inverse        // Toast text and info icon color
+
+theme.colors.content.success.primary // Success icon color
+theme.colors.content.warning.primary // Warning icon color
+theme.colors.content.alert.primary   // Error icon color
 ```
 
+### Sizing
+
+Toast dimensions come from `theme.sizing.toast()`:
+
+| Token | Value | Description |
+| :---- | :---- | :---------- |
+| `minHeight` | `64` | Minimum toast height |
+| `paddingHorizontal` | `12` | Left/right padding |
+| `paddingVertical` | `8` | Top/bottom padding |
+| `borderRadius` | `4` | Corner radius |
+| `gap` | `12` | Space between icon, text, and close button |
+| `iconSize` | `24` | Icon dimensions |
+| `closeButtonSize` | `24` | Close button tap target |
+| `closeIconSize` | `20` | Close icon dimensions |
+| `fontSize` | `16` | Message text size |
+| `lineHeight` | `20` | Message line height |
+| `maxWidth` | `400` | Maximum toast width |
+| `containerPadding` | `12` | Padding between toast container and screen edges |
+| `groupGap` | `4` | Vertical gap between stacked toasts |
+
 ## Platform Support
 
-This package supports both React (web) and React Native with identical API:
+This package supports both React (web) and React Native with an identical API.
 
 ### React (Web)
-- Uses `ReactDOM.createPortal` for fixed positioning at the document body level
-- Toasts appear above all other content regardless of z-index stacking context
-- Works with any React web framework (Next.js, Vite, Create React App, etc.)
+
+- Uses `ReactDOM.createPortal` to render toasts at the document body level
+- Toasts appear above all other content regardless of z-index stacking contexts
+- Works with any React web framework (Next.js, Vite, Create React App, Remix, etc.)
 
 ### React Native
+
 - Uses absolute positioning within the app container
 - Toasts render within the component tree (no portal equivalent in RN)
 - Works with React Navigation, Expo, and bare React Native projects
 
-### Cross-Platform Usage Notes
+### Cross-Platform Comparison
 
 | Feature | Web | React Native |
 | :------ | :-- | :----------- |
-| Provider setup | Wrap with `ToastProvider` | Wrap with `XUIProvider` + `ToastProvider` |
+| Provider setup | `ToastProvider` | `XUIProvider` + `ToastProvider` |
 | Hook API | `useToast()` | `useToast()` (identical) |
-| Event handlers | `onClick` (optional) | `onPress` |
+| Event handlers | `onClick` | `onPress` |
 | Root container | Any element | Must have `flex: 1` |
 | Position: top | Fixed to viewport top | Absolute to container top |
 | Position: bottom | Fixed to viewport bottom | Absolute to container bottom |
+| Rendering | `ReactDOM.createPortal` into `document.body` | Absolute-positioned `Box` in tree |
 
 ### React Native Example with Navigation
 
@@ -338,7 +496,47 @@ export default function App() {
 
 ## Accessibility
 
-- Toasts use `role="alert"` and `aria-live="polite"` for screen reader announcements
-- Close button includes `aria-label="Dismiss toast"`
-- Icons are decorative and do not affect accessibility
-- Keyboard users can dismiss toasts via the close button
+- Each toast renders with `role="alert"` and `aria-live="polite"` for screen reader announcements
+- The close button includes `aria-label="Dismiss toast"` for assistive technology
+- Icons are decorative and do not interfere with accessibility
+- Keyboard users can Tab to the close button and press Enter to dismiss
+- Toast messages are limited to 2 lines (`numberOfLines={2}`) for readability
+
+## Troubleshooting
+
+### "useToast must be used within a ToastProvider"
+
+The `useToast` hook was called in a component that is not a descendant of `ToastProvider`. Ensure your component tree has a `ToastProvider` ancestor:
+
+```tsx
+// Correct — hook is inside the provider tree
+<ToastProvider>
+  <ComponentThatCallsUseToast />
+</ToastProvider>
+
+// Wrong — hook is outside the provider
+<ComponentThatCallsUseToast />
+<ToastProvider>
+  <OtherContent />
+</ToastProvider>
+```
+
+### Toasts not visible on React Native
+
+Make sure the container inside `ToastProvider` has `flex: 1`. Without this, the absolute-positioned toast group has no reference height:
+
+```tsx
+<ToastProvider>
+  <View style={{ flex: 1 }}> {/* Required */}
+    <App />
+  </View>
+</ToastProvider>
+```
+
+### Toasts appear behind a modal or overlay
+
+On web, `ToastGroup` uses `z-index: 9999`. If your modal or overlay uses a higher z-index, the toasts may be hidden. Consider placing the `ToastProvider` above your modal provider in the tree, or adjusting z-index values.
+
+### Auto-dismiss not working
+
+Ensure `duration` is not set to `0`. A duration of `0` disables auto-dismiss. Check both the per-toast `duration` option and the provider's `defaultDuration` prop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-toast",
-  "version": "0.120.0",
+  "version": "0.121.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -14,9 +14,9 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.120.0",
-    "@xsolla/xui-icons": "0.120.0",
-    "@xsolla/xui-primitives-core": "0.120.0"
+    "@xsolla/xui-core": "0.121.0",
+    "@xsolla/xui-icons": "0.121.0",
+    "@xsolla/xui-primitives-core": "0.121.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",