@xsolla/xui-toast 0.99.0 → 0.101.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +319 -26
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,51 +1,344 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Toast
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A cross-platform React toast notification system for displaying brief, auto-dismissing messages. Includes a provider, hook API, and support for multiple toast variants.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
+
npm install @xsolla/xui-toast
|
|
9
|
+
# or
|
|
8
10
|
yarn add @xsolla/xui-toast
|
|
9
11
|
```
|
|
10
12
|
|
|
11
|
-
##
|
|
13
|
+
## Demo
|
|
14
|
+
|
|
15
|
+
### Basic Setup (React Web)
|
|
16
|
+
|
|
17
|
+
Wrap your application with `ToastProvider`:
|
|
12
18
|
|
|
13
19
|
```tsx
|
|
14
|
-
import
|
|
20
|
+
import * as React from 'react';
|
|
21
|
+
import { ToastProvider } from '@xsolla/xui-toast';
|
|
22
|
+
|
|
23
|
+
export default function App() {
|
|
24
|
+
return (
|
|
25
|
+
<ToastProvider>
|
|
26
|
+
<YourApp />
|
|
27
|
+
</ToastProvider>
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Basic Setup (React Native)
|
|
33
|
+
|
|
34
|
+
For React Native, wrap your app entry point with both `XUIProvider` and `ToastProvider`:
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
import React from 'react';
|
|
38
|
+
import { View } from 'react-native';
|
|
39
|
+
import { XUIProvider } from '@xsolla/xui-core';
|
|
40
|
+
import { ToastProvider } from '@xsolla/xui-toast';
|
|
41
|
+
import { MainNavigator } from './navigation';
|
|
42
|
+
|
|
43
|
+
export default function App() {
|
|
44
|
+
return (
|
|
45
|
+
<XUIProvider mode="dark">
|
|
46
|
+
<ToastProvider position="top">
|
|
47
|
+
<View style={{ flex: 1 }}>
|
|
48
|
+
<MainNavigator />
|
|
49
|
+
</View>
|
|
50
|
+
</ToastProvider>
|
|
51
|
+
</XUIProvider>
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
```
|
|
15
55
|
|
|
16
|
-
|
|
56
|
+
> **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.
|
|
57
|
+
|
|
58
|
+
### Showing Toasts (React Web)
|
|
59
|
+
|
|
60
|
+
Use the `useToast` hook to show toasts:
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
import * as React from 'react';
|
|
64
|
+
import { useToast } from '@xsolla/xui-toast';
|
|
65
|
+
|
|
66
|
+
export default function ToastExample() {
|
|
17
67
|
const toast = useToast();
|
|
18
|
-
return <button onClick={() => toast.success('Saved!')}>Save</button>;
|
|
19
|
-
};
|
|
20
68
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
69
|
+
return (
|
|
70
|
+
<div style={{ display: 'flex', gap: 8 }}>
|
|
71
|
+
<button onClick={() => toast.success('Quest has been activated')}>
|
|
72
|
+
Success
|
|
73
|
+
</button>
|
|
74
|
+
<button onClick={() => toast.info('You received 50 Xsolla Points')}>
|
|
75
|
+
Info
|
|
76
|
+
</button>
|
|
77
|
+
<button onClick={() => toast.warning('Your session is about to expire')}>
|
|
78
|
+
Warning
|
|
79
|
+
</button>
|
|
80
|
+
<button onClick={() => toast.error('Failed to save changes')}>
|
|
81
|
+
Error
|
|
82
|
+
</button>
|
|
83
|
+
</div>
|
|
84
|
+
);
|
|
85
|
+
}
|
|
26
86
|
```
|
|
27
87
|
|
|
28
|
-
|
|
88
|
+
### Showing Toasts (React Native)
|
|
29
89
|
|
|
30
|
-
|
|
31
|
-
- `useToast` — hook with `success`, `info`, `warning`, `error`, `toast`, `dismiss`, `dismissAll`
|
|
32
|
-
- `Toast` — individual toast item (used internally; rarely needed directly)
|
|
90
|
+
The `useToast` hook works identically in React Native. Use `onPress` instead of `onClick`:
|
|
33
91
|
|
|
34
|
-
|
|
92
|
+
```tsx
|
|
93
|
+
import React from 'react';
|
|
94
|
+
import { View } from 'react-native';
|
|
95
|
+
import { Button } from '@xsolla/xui-button';
|
|
96
|
+
import { useToast } from '@xsolla/xui-toast';
|
|
97
|
+
|
|
98
|
+
export default function ToastExample() {
|
|
99
|
+
const toast = useToast();
|
|
100
|
+
|
|
101
|
+
return (
|
|
102
|
+
<View style={{ gap: 8 }}>
|
|
103
|
+
<Button onPress={() => toast.success('Quest has been activated')}>
|
|
104
|
+
Success
|
|
105
|
+
</Button>
|
|
106
|
+
<Button onPress={() => toast.info('You received 50 Xsolla Points')}>
|
|
107
|
+
Info
|
|
108
|
+
</Button>
|
|
109
|
+
<Button onPress={() => toast.warning('Your session is about to expire')}>
|
|
110
|
+
Warning
|
|
111
|
+
</Button>
|
|
112
|
+
<Button onPress={() => toast.error('Failed to save changes')}>
|
|
113
|
+
Error
|
|
114
|
+
</Button>
|
|
115
|
+
</View>
|
|
116
|
+
);
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### Toast Variants
|
|
121
|
+
|
|
122
|
+
```tsx
|
|
123
|
+
import * as React from 'react';
|
|
124
|
+
import { Toast } from '@xsolla/xui-toast';
|
|
125
|
+
|
|
126
|
+
export default function ToastVariants() {
|
|
127
|
+
return (
|
|
128
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 8, maxWidth: 400 }}>
|
|
129
|
+
<Toast id="1" variant="success" message="Quest has been activated" onClose={() => {}} />
|
|
130
|
+
<Toast id="2" variant="info" message="You received 50 Xsolla Points" onClose={() => {}} />
|
|
131
|
+
<Toast id="3" variant="warning" message="Your session is about to expire" onClose={() => {}} />
|
|
132
|
+
<Toast id="4" variant="error" message="Failed to save changes" onClose={() => {}} />
|
|
133
|
+
</div>
|
|
134
|
+
);
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### Custom Duration
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
import * as React from 'react';
|
|
142
|
+
import { useToast } from '@xsolla/xui-toast';
|
|
143
|
+
|
|
144
|
+
export default function CustomDuration() {
|
|
145
|
+
const toast = useToast();
|
|
146
|
+
|
|
147
|
+
return (
|
|
148
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
|
|
149
|
+
<button onClick={() => toast.toast({ message: 'Stays for 10 seconds', duration: 10000 })}>
|
|
150
|
+
Long Duration (10s)
|
|
151
|
+
</button>
|
|
152
|
+
<button onClick={() => toast.toast({ message: 'Stays for 2 seconds', duration: 2000 })}>
|
|
153
|
+
Short Duration (2s)
|
|
154
|
+
</button>
|
|
155
|
+
<button onClick={() => toast.toast({ message: 'Dismiss me manually', duration: 0 })}>
|
|
156
|
+
No Auto-Dismiss
|
|
157
|
+
</button>
|
|
158
|
+
</div>
|
|
159
|
+
);
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Dismissing Toasts
|
|
164
|
+
|
|
165
|
+
```tsx
|
|
166
|
+
import * as React from 'react';
|
|
167
|
+
import { useToast } from '@xsolla/xui-toast';
|
|
168
|
+
|
|
169
|
+
export default function DismissExample() {
|
|
170
|
+
const toast = useToast();
|
|
171
|
+
const [lastToastId, setLastToastId] = React.useState<string | null>(null);
|
|
172
|
+
|
|
173
|
+
const showToast = () => {
|
|
174
|
+
const id = toast.info('New notification');
|
|
175
|
+
setLastToastId(id);
|
|
176
|
+
};
|
|
177
|
+
|
|
178
|
+
return (
|
|
179
|
+
<div style={{ display: 'flex', gap: 8 }}>
|
|
180
|
+
<button onClick={showToast}>Show Toast</button>
|
|
181
|
+
<button onClick={() => lastToastId && toast.dismiss(lastToastId)}>
|
|
182
|
+
Dismiss Last
|
|
183
|
+
</button>
|
|
184
|
+
<button onClick={() => toast.dismissAll()}>Dismiss All</button>
|
|
185
|
+
</div>
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Position Configuration
|
|
191
|
+
|
|
192
|
+
```tsx
|
|
193
|
+
import * as React from 'react';
|
|
194
|
+
import { ToastProvider, useToast } from '@xsolla/xui-toast';
|
|
195
|
+
|
|
196
|
+
function ToastTrigger() {
|
|
197
|
+
const toast = useToast();
|
|
198
|
+
return <button onClick={() => toast.info('Toast at the bottom!')}>Show Toast</button>;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
export default function BottomPosition() {
|
|
202
|
+
return (
|
|
203
|
+
<ToastProvider position="bottom">
|
|
204
|
+
<ToastTrigger />
|
|
205
|
+
</ToastProvider>
|
|
206
|
+
);
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## API Reference
|
|
35
211
|
|
|
36
212
|
### ToastProvider
|
|
37
213
|
|
|
214
|
+
The root provider component that manages toast state and renders the toast container.
|
|
215
|
+
|
|
216
|
+
**ToastProvider Props:**
|
|
217
|
+
|
|
38
218
|
| Prop | Type | Default | Description |
|
|
39
|
-
|
|
40
|
-
|
|
|
41
|
-
|
|
|
219
|
+
| :--- | :--- | :------ | :---------- |
|
|
220
|
+
| children | `ReactNode` | - | Application content. |
|
|
221
|
+
| position | `"top" \| "bottom"` | `"top"` | Position of the toast container. |
|
|
222
|
+
| defaultDuration | `number` | `5000` | Default auto-dismiss duration in milliseconds. |
|
|
223
|
+
|
|
224
|
+
### useToast
|
|
225
|
+
|
|
226
|
+
A hook that provides methods to show and dismiss toasts. Must be used within a `ToastProvider`.
|
|
227
|
+
|
|
228
|
+
**useToast Return Value:**
|
|
229
|
+
|
|
230
|
+
| Method | Signature | Description |
|
|
231
|
+
| :----- | :-------- | :---------- |
|
|
232
|
+
| toast | `(options: ToastOptions) => string` | Show a toast with custom options. Returns the toast ID. |
|
|
233
|
+
| success | `(message: string, options?) => string` | Show a success toast. |
|
|
234
|
+
| info | `(message: string, options?) => string` | Show an info toast. |
|
|
235
|
+
| warning | `(message: string, options?) => string` | Show a warning toast. |
|
|
236
|
+
| error | `(message: string, options?) => string` | Show an error toast. |
|
|
237
|
+
| dismiss | `(id: string) => void` | Dismiss a specific toast by ID. |
|
|
238
|
+
| dismissAll | `() => void` | Dismiss all toasts. |
|
|
42
239
|
|
|
43
240
|
### Toast
|
|
44
241
|
|
|
242
|
+
The individual toast component. Typically used internally by `ToastProvider`, but can be used standalone.
|
|
243
|
+
|
|
244
|
+
**Toast Props:**
|
|
245
|
+
|
|
45
246
|
| Prop | Type | Default | Description |
|
|
46
|
-
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
|
50
|
-
|
|
|
51
|
-
|
|
|
247
|
+
| :--- | :--- | :------ | :---------- |
|
|
248
|
+
| id | `string` | - | Unique toast identifier. |
|
|
249
|
+
| message | `string` | - | Toast message text. |
|
|
250
|
+
| variant | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Toast variant/style. |
|
|
251
|
+
| icon | `ReactNode` | - | Custom icon (optional, uses default icons per variant). |
|
|
252
|
+
| onClose | `() => void` | - | Callback when close button is clicked. If not provided, close button is hidden. |
|
|
253
|
+
|
|
254
|
+
### ToastOptions
|
|
255
|
+
|
|
256
|
+
Options passed to the `toast()` method.
|
|
257
|
+
|
|
258
|
+
| Property | Type | Default | Description |
|
|
259
|
+
| :------- | :--- | :------ | :---------- |
|
|
260
|
+
| message | `string` | - | Toast message text. |
|
|
261
|
+
| variant | `"success" \| "info" \| "warning" \| "error"` | `"info"` | Toast variant. |
|
|
262
|
+
| icon | `ReactNode` | - | Custom icon. |
|
|
263
|
+
| duration | `number` | Provider's `defaultDuration` | Auto-dismiss duration. Use `0` to disable auto-dismiss. |
|
|
264
|
+
|
|
265
|
+
### Variant Values
|
|
266
|
+
|
|
267
|
+
| Variant | Use Case | Default Icon |
|
|
268
|
+
| :------ | :------- | :----------- |
|
|
269
|
+
| `success` | Positive outcomes, confirmations | Check circle |
|
|
270
|
+
| `info` | General information, neutral messages | Info circle |
|
|
271
|
+
| `warning` | Caution, requires attention | Alert circle |
|
|
272
|
+
| `error` | Errors, failures, critical issues | Alert circle |
|
|
273
|
+
|
|
274
|
+
## Theming
|
|
275
|
+
|
|
276
|
+
Toast uses the inverse color scheme (dark background with light text):
|
|
277
|
+
|
|
278
|
+
```typescript
|
|
279
|
+
// Toast styling accessed via theme
|
|
280
|
+
theme.colors.background.inverse // Toast background (black)
|
|
281
|
+
theme.colors.content.inverse // Toast text (white)
|
|
282
|
+
|
|
283
|
+
// Variant-specific icon colors
|
|
284
|
+
theme.colors.content.success.primary // Success icon
|
|
285
|
+
theme.colors.content.warning.primary // Warning icon
|
|
286
|
+
theme.colors.content.alert.primary // Error icon
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
## Platform Support
|
|
290
|
+
|
|
291
|
+
This package supports both React (web) and React Native with identical API:
|
|
292
|
+
|
|
293
|
+
### React (Web)
|
|
294
|
+
- Uses `ReactDOM.createPortal` for fixed positioning at the document body level
|
|
295
|
+
- Toasts appear above all other content regardless of z-index stacking context
|
|
296
|
+
- Works with any React web framework (Next.js, Vite, Create React App, etc.)
|
|
297
|
+
|
|
298
|
+
### React Native
|
|
299
|
+
- Uses absolute positioning within the app container
|
|
300
|
+
- Toasts render within the component tree (no portal equivalent in RN)
|
|
301
|
+
- Works with React Navigation, Expo, and bare React Native projects
|
|
302
|
+
|
|
303
|
+
### Cross-Platform Usage Notes
|
|
304
|
+
|
|
305
|
+
| Feature | Web | React Native |
|
|
306
|
+
| :------ | :-- | :----------- |
|
|
307
|
+
| Provider setup | Wrap with `ToastProvider` | Wrap with `XUIProvider` + `ToastProvider` |
|
|
308
|
+
| Hook API | `useToast()` | `useToast()` (identical) |
|
|
309
|
+
| Event handlers | `onClick` (optional) | `onPress` |
|
|
310
|
+
| Root container | Any element | Must have `flex: 1` |
|
|
311
|
+
| Position: top | Fixed to viewport top | Absolute to container top |
|
|
312
|
+
| Position: bottom | Fixed to viewport bottom | Absolute to container bottom |
|
|
313
|
+
|
|
314
|
+
### React Native Example with Navigation
|
|
315
|
+
|
|
316
|
+
```tsx
|
|
317
|
+
import React from 'react';
|
|
318
|
+
import { NavigationContainer } from '@react-navigation/native';
|
|
319
|
+
import { SafeAreaProvider } from 'react-native-safe-area-context';
|
|
320
|
+
import { XUIProvider } from '@xsolla/xui-core';
|
|
321
|
+
import { ToastProvider } from '@xsolla/xui-toast';
|
|
322
|
+
import { RootNavigator } from './navigation';
|
|
323
|
+
|
|
324
|
+
export default function App() {
|
|
325
|
+
return (
|
|
326
|
+
<SafeAreaProvider>
|
|
327
|
+
<XUIProvider mode="dark">
|
|
328
|
+
<ToastProvider position="top">
|
|
329
|
+
<NavigationContainer>
|
|
330
|
+
<RootNavigator />
|
|
331
|
+
</NavigationContainer>
|
|
332
|
+
</ToastProvider>
|
|
333
|
+
</XUIProvider>
|
|
334
|
+
</SafeAreaProvider>
|
|
335
|
+
);
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
## Accessibility
|
|
340
|
+
|
|
341
|
+
- Toasts use `role="alert"` and `aria-live="polite"` for screen reader announcements
|
|
342
|
+
- Close button includes `aria-label="Dismiss toast"`
|
|
343
|
+
- Icons are decorative and do not affect accessibility
|
|
344
|
+
- Keyboard users can dismiss toasts via the close button
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xsolla/xui-toast",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.101.0",
|
|
4
4
|
"main": "./web/index.js",
|
|
5
5
|
"module": "./web/index.mjs",
|
|
6
6
|
"types": "./web/index.d.ts",
|
|
@@ -14,9 +14,9 @@
|
|
|
14
14
|
"test:coverage": "vitest run --coverage"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|
|
17
|
-
"@xsolla/xui-core": "0.
|
|
18
|
-
"@xsolla/xui-icons": "0.
|
|
19
|
-
"@xsolla/xui-primitives-core": "0.
|
|
17
|
+
"@xsolla/xui-core": "0.101.0",
|
|
18
|
+
"@xsolla/xui-icons": "0.101.0",
|
|
19
|
+
"@xsolla/xui-primitives-core": "0.101.0"
|
|
20
20
|
},
|
|
21
21
|
"peerDependencies": {
|
|
22
22
|
"react": ">=16.8.0",
|