@xsolla/xui-toast 0.150.0 → 0.151.0

package/README.md

@@ -1,543 +1,323 @@
 # 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.
+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.
 
 ## Installation
 
 ```bash
-npm install @xsolla/xui-toast @xsolla/xui-core
-# or
-yarn add @xsolla/xui-toast @xsolla/xui-core
+npm install @xsolla/xui-toast
 ```
 
-**Peer dependencies:** `react >= 16.8.0`, `styled-components >= 4`
+## Imports
 
-## Architecture
-
-The toast system uses a **Provider → Context → Hook** pattern:
-
-```
-┌─────────────────────────────────────────────────┐
-│  ToastProvider                                   │
-│  ┌────────────┐  ┌───────────────────────────┐  │
-│  │ ToastContext│  │ ToastGroup (portal / abs) │  │
-│  │  - toasts  │  │  ┌───────┐ ┌───────┐      │  │
-│  │  - addToast│──▶  │ Toast │ │ Toast │ ...  │  │
-│  │  - dismiss │  │  └───────┘ └───────┘      │  │
-│  └────────────┘  └───────────────────────────┘  │
-│        ▲                                         │
-│        │  useToast()                             │
-│  ┌─────┴──────┐                                  │
-│  │  Your App  │                                  │
-│  └────────────┘                                  │
-└─────────────────────────────────────────────────┘
+```tsx
+import {
+  Toast,
+  ToastProvider,
+  ToastGroup,
+  ToastContext,
+  useToast,
+  type ToastProps,
+  type ToastOptions,
+  type ToastVariant,
+  type ToastPosition,
+  type ToastAlign,
+  type UseToastReturn,
+} from '@xsolla/xui-toast';
 ```
 
-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`
+## Quick start
 
-**React (Web):**
+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 } from '@xsolla/xui-toast';
+import { ToastProvider, useToast } from '@xsolla/xui-toast';
 
-export default function App() {
+function SaveButton() {
+  const toast = useToast();
   return (
-    <XUIProvider initialMode="dark" initialProductContext="b2b">
-      <ToastProvider>
-        <YourApp />
-      </ToastProvider>
-    </XUIProvider>
+    <button onClick={() => toast.success('Saved successfully')}>Save</button>
   );
 }
-```
-
-**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>
+    <XUIProvider initialMode="dark">
+      <ToastProvider>
+        <SaveButton />
       </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.
+> **React Native:** ensure the root container under `ToastProvider` has `flex: 1` so absolute-positioned toasts have a reference height.
 
-### 2. Show toasts with `useToast`
+## API Reference
 
-```tsx
-import { useToast } from '@xsolla/xui-toast';
+### `<ToastProvider>`
 
-function SaveButton() {
-  const toast = useToast();
+Root provider. Manages toast state, auto-dismiss timers, and renders the `ToastGroup`.
 
-  const handleSave = async () => {
-    try {
-      await saveData();
-      toast.success('Changes saved successfully');
-    } catch {
-      toast.error('Failed to save changes');
-    }
-  };
+| 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. |
 
-  return <button onClick={handleSave}>Save</button>;
-}
-```
+### `<Toast>`
 
-## Demo
+The individual toast cell. Used internally by `ToastGroup`, but can be rendered standalone for static display.
 
-### Showing Toast Variants
+| 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. |
 
-Each variant conveys a different semantic meaning and displays a corresponding icon:
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-```tsx
-import { useToast } from '@xsolla/xui-toast';
+### `<ToastGroup>`
 
-export default function ToastExample() {
-  const toast = useToast();
+Renders the stack of visible toasts. On web uses `ReactDOM.createPortal` to escape stacking contexts; on React Native uses absolute positioning.
 
-  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>
-  );
+| 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. |
+
+Inherits `ThemeOverrideProps`.
+
+### `useToast()`
+
+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. |
+
+### `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. |
+
+### `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. |
+
+### `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';
+
+function ActiveCount() {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('Must be within ToastProvider');
+  return <span>Active toasts: {ctx.toasts.length}</span>;
 }
 ```
 
-### Showing Toasts (React Native)
+## Examples
 
-The `useToast` hook works identically in React Native. Use `onPress` instead of `onClick`:
+### Variants
 
 ```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { Button } from '@xsolla/xui-button';
+import * as React from 'react';
 import { useToast } from '@xsolla/xui-toast';
 
-export default function ToastExample() {
+export default function Variants() {
   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>
+    <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>
   );
 }
 ```
 
-### Toast Variants (Standalone `Toast` Component)
-
-The `Toast` component can be used standalone outside the provider for static display or custom layouts:
+### Standalone Toast (no provider)
 
 ```tsx
+import * as React from 'react';
 import { Toast } from '@xsolla/xui-toast';
 
-export default function ToastVariants() {
+export default function Standalone() {
   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={() => {}} />
+      <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>
   );
 }
 ```
 
-### Custom Duration
-
-Control how long toasts remain visible. The default is 5000ms. Set `duration: 0` to disable auto-dismiss entirely:
+### Custom duration
 
 ```tsx
+import * as React from 'react';
 import { useToast } from '@xsolla/xui-toast';
 
-export default function CustomDuration() {
+export default function Duration() {
   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 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>
   );
 }
 ```
 
-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:
+### Custom icon
 
 ```tsx
+import * as React from 'react';
 import { useToast } from '@xsolla/xui-toast';
-import { Star } from '@xsolla/xui-icons';
+import { Star } from '@xsolla/xui-icons-base';
 
-function CustomIconExample() {
+export default function CustomIcon() {
   const toast = useToast();
-
   return (
     <button
       onClick={() =>
-        toast.toast({
-          message: 'You earned a gold star!',
-          variant: 'success',
-          icon: <Star />,
-        })
+        toast.toast({ message: 'You earned a gold star', variant: 'success', icon: <Star /> })
       }
     >
-      Show Custom Icon Toast
+      Show
     </button>
   );
 }
 ```
 
-### Dismissing Toasts Programmatically
-
-Every `toast.*()` call returns a unique ID. Use it to dismiss a specific toast:
+### Programmatic dismiss
 
 ```tsx
 import * as React from 'react';
 import { useToast } from '@xsolla/xui-toast';
 
-export default function DismissExample() {
+export default function Dismiss() {
   const toast = useToast();
-  const [lastToastId, setLastToastId] = React.useState<string | null>(null);
-
-  const showToast = () => {
-    const id = toast.info('New notification');
-    setLastToastId(id);
-  };
+  const [lastId, setLastId] = React.useState<string | null>(null);
 
   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>
+      <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 Configuration
-
-Toasts can be anchored to the top or bottom of the viewport:
+### Position and alignment
 
 ```tsx
+import * as React from 'react';
 import { ToastProvider, useToast } from '@xsolla/xui-toast';
 
-function ToastTrigger() {
+function Trigger() {
   const toast = useToast();
-  return <button onClick={() => toast.info('Toast at the bottom!')}>Show Toast</button>;
+  return <button onClick={() => toast.info('Bottom-right toast')}>Show</button>;
 }
 
-export default function BottomPosition() {
+export default function BottomRight() {
   return (
-    <ToastProvider position="bottom">
-      <ToastTrigger />
+    <ToastProvider position="bottom" align="right" maxWidth={400}>
+      <Trigger />
     </ToastProvider>
   );
 }
 ```
 
-### Multiple Toasts
+### React Native
 
-Multiple toasts stack vertically in the order they are created:
+The `useToast` hook is identical on React Native; use `onPress` instead of `onClick`.
 
 ```tsx
-import { useToast } from '@xsolla/xui-toast';
+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 MultipleToastsExample() {
+function Trigger() {
   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>;
+  return <Button onPress={() => toast.success('Saved')}>Save</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>;
+export default function App() {
+  return (
+    <XUIProvider initialMode="dark">
+      <ToastProvider position="top">
+        <View style={{ flex: 1 }}>
+          <Trigger />
+        </View>
+      </ToastProvider>
+    </XUIProvider>
+  );
 }
 ```
 
-### 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
+## Platform support
 
-### Cross-Platform Comparison
-
-| Feature | Web | React Native |
-| :------ | :-- | :----------- |
-| Provider setup | `ToastProvider` | `XUIProvider` + `ToastProvider` |
-| Hook API | `useToast()` | `useToast()` (identical) |
+| 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` |
-| 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
+- 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.
 
 ## 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.
+- **"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.
 
-### Auto-dismiss not working
+## Related
 
-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.
+- [Notification](./notification.md) — declarative toast/inline notification.
+- [NotificationPanel](./notification-panel.md) — full-width inline banner.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-toast",
-  "version": "0.150.0",
+  "version": "0.151.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.150.0",
-    "@xsolla/xui-icons": "0.150.0",
-    "@xsolla/xui-primitives-core": "0.150.0"
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-icons": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",