@xsolla/xui-toast 0.148.0 → 0.148.2

package/README.md

@@ -0,0 +1,543 @@
+# Toast
+
+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 @xsolla/xui-core
+# or
+yarn add @xsolla/xui-toast @xsolla/xui-core
+```
+
+**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  │                                  │
+│  └────────────┘                                  │
+└─────────────────────────────────────────────────┘
+```
+
+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.
+
+## Quick Start
+
+### 1. Wrap your app with `ToastProvider`
+
+**React (Web):**
+
+```tsx
+import { XUIProvider } from '@xsolla/xui-core';
+import { ToastProvider } from '@xsolla/xui-toast';
+
+export default function App() {
+  return (
+    <XUIProvider initialMode="dark" initialProductContext="b2b">
+      <ToastProvider>
+        <YourApp />
+      </ToastProvider>
+    </XUIProvider>
+  );
+}
+```
+
+**React Native:**
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { XUIProvider } from '@xsolla/xui-core';
+import { ToastProvider } from '@xsolla/xui-toast';
+import { MainNavigator } from './navigation';
+
+export default function App() {
+  return (
+    <XUIProvider mode="dark">
+      <ToastProvider position="top">
+        <View style={{ flex: 1 }}>
+          <MainNavigator />
+        </View>
+      </ToastProvider>
+    </XUIProvider>
+  );
+}
+```
+
+> **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.
+
+### 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
+
+Each variant conveys a different semantic meaning and displays a corresponding icon:
+
+```tsx
+import { useToast } from '@xsolla/xui-toast';
+
+export default function ToastExample() {
+  const toast = useToast();
+
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <button onClick={() => toast.success('Quest has been activated')}>
+        Success
+      </button>
+      <button onClick={() => toast.info('You received 50 Xsolla Points')}>
+        Info
+      </button>
+      <button onClick={() => toast.warning('Your session is about to expire')}>
+        Warning
+      </button>
+      <button onClick={() => toast.error('Failed to save changes')}>
+        Error
+      </button>
+    </div>
+  );
+}
+```
+
+### Showing Toasts (React Native)
+
+The `useToast` hook works identically in React Native. Use `onPress` instead of `onClick`:
+
+```tsx
+import React from 'react';
+import { View } from 'react-native';
+import { Button } from '@xsolla/xui-button';
+import { useToast } from '@xsolla/xui-toast';
+
+export default function ToastExample() {
+  const toast = useToast();
+
+  return (
+    <View style={{ gap: 8 }}>
+      <Button onPress={() => toast.success('Quest has been activated')}>
+        Success
+      </Button>
+      <Button onPress={() => toast.info('You received 50 Xsolla Points')}>
+        Info
+      </Button>
+      <Button onPress={() => toast.warning('Your session is about to expire')}>
+        Warning
+      </Button>
+      <Button onPress={() => toast.error('Failed to save changes')}>
+        Error
+      </Button>
+    </View>
+  );
+}
+```
+
+### Toast Variants (Standalone `Toast` Component)
+
+The `Toast` component can be used standalone outside the provider for static display or custom layouts:
+
+```tsx
+import { Toast } from '@xsolla/xui-toast';
+
+export default function ToastVariants() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, maxWidth: 400 }}>
+      <Toast id="1" variant="success" message="Quest has been activated" onClose={() => {}} />
+      <Toast id="2" variant="info" message="You received 50 Xsolla Points" onClose={() => {}} />
+      <Toast id="3" variant="warning" message="Your session is about to expire" onClose={() => {}} />
+      <Toast id="4" variant="error" message="Failed to save changes" onClose={() => {}} />
+    </div>
+  );
+}
+```
+
+### Custom Duration
+
+Control how long toasts remain visible. The default is 5000ms. Set `duration: 0` to disable auto-dismiss entirely:
+
+```tsx
+import { useToast } from '@xsolla/xui-toast';
+
+export default function CustomDuration() {
+  const toast = useToast();
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+      <button onClick={() => toast.toast({ message: 'Stays for 10 seconds', duration: 10000 })}>
+        Long Duration (10s)
+      </button>
+      <button onClick={() => toast.toast({ message: 'Stays for 2 seconds', duration: 2000 })}>
+        Short Duration (2s)
+      </button>
+      <button onClick={() => toast.toast({ message: 'Dismiss me manually', duration: 0 })}>
+        No Auto-Dismiss
+      </button>
+    </div>
+  );
+}
+```
+
+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';
+import { useToast } from '@xsolla/xui-toast';
+
+export default function DismissExample() {
+  const toast = useToast();
+  const [lastToastId, setLastToastId] = React.useState<string | null>(null);
+
+  const showToast = () => {
+    const id = toast.info('New notification');
+    setLastToastId(id);
+  };
+
+  return (
+    <div style={{ display: 'flex', gap: 8 }}>
+      <button onClick={showToast}>Show Toast</button>
+      <button onClick={() => lastToastId && toast.dismiss(lastToastId)}>
+        Dismiss Last
+      </button>
+      <button onClick={() => toast.dismissAll()}>Dismiss All</button>
+    </div>
+  );
+}
+```
+
+### Position Configuration
+
+Toasts can be anchored to the top or bottom of the viewport:
+
+```tsx
+import { ToastProvider, useToast } from '@xsolla/xui-toast';
+
+function ToastTrigger() {
+  const toast = useToast();
+  return <button onClick={() => toast.info('Toast at the bottom!')}>Show Toast</button>;
+}
+
+export default function BottomPosition() {
+  return (
+    <ToastProvider position="bottom">
+      <ToastTrigger />
+    </ToastProvider>
+  );
+}
+```
+
+### 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.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| `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. |
+| `maxWidth` | `number` | `100%` | Maximum width of the toast container in pixels. If not set, toasts stretch to full viewport width. |
+
+### useToast
+
+A hook that returns methods to show and dismiss toasts. Must be called within a `ToastProvider` — throws an error otherwise.
+
+**Return type: `UseToastReturn`**
+
+| Method | Signature | Description |
+| :----- | :-------- | :---------- |
+| `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 notification component. Used internally by `ToastGroup`, but can be rendered standalone for static display.
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :------ | :---------- |
+| `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 object passed to the `toast()` method or as the second argument to shorthand methods.
+
+| Property | Type | Default | Description |
+| :------- | :--- | :------ | :---------- |
+| `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';
+
+function CustomToastConsumer() {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('Must be within ToastProvider');
+
+  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) to stand out from the application content:
+
+### Colors
+
+```typescript
+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 (theme default; overridden by `ToastProvider maxWidth` prop) |
+| `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 an identical API.
+
+### React (Web)
+
+- 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 Comparison
+
+| Feature | Web | React Native |
+| :------ | :-- | :----------- |
+| Provider setup | `ToastProvider` | `XUIProvider` + `ToastProvider` |
+| Hook API | `useToast()` | `useToast()` (identical) |
+| 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
+
+```tsx
+import React from 'react';
+import { NavigationContainer } from '@react-navigation/native';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { XUIProvider } from '@xsolla/xui-core';
+import { ToastProvider } from '@xsolla/xui-toast';
+import { RootNavigator } from './navigation';
+
+export default function App() {
+  return (
+    <SafeAreaProvider>
+      <XUIProvider mode="dark">
+        <ToastProvider position="top">
+          <NavigationContainer>
+            <RootNavigator />
+          </NavigationContainer>
+        </ToastProvider>
+      </XUIProvider>
+    </SafeAreaProvider>
+  );
+}
+```
+
+## Accessibility
+
+- 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.148.0",
+  "version": "0.148.2",
   "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.148.0",
-    "@xsolla/xui-icons": "0.148.0",
-    "@xsolla/xui-primitives-core": "0.148.0"
+    "@xsolla/xui-core": "0.148.2",
+    "@xsolla/xui-icons": "0.148.2",
+    "@xsolla/xui-primitives-core": "0.148.2"
   },
   "peerDependencies": {
     "react": ">=16.8.0",