@editora/toast 2.0.9 โ 2.1.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/CHANGELOG.md +28 -0
- package/README.md +376 -860
- package/dist/core/ToastManager.d.ts +1 -1
- package/dist/core/ToastRenderer.d.ts +24 -3
- package/dist/core/ToastStack.d.ts +8 -0
- package/dist/core/icons.d.ts +2 -0
- package/dist/core/types.d.ts +3 -1
- package/dist/index.cjs.js +1 -1
- package/dist/index.d.ts +13 -16
- package/dist/index.esm.js +490 -310
- package/dist/index.umd.js +1 -1
- package/dist/toast.css +467 -744
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,955 +1,471 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
>
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
>
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
### Error Handling
|
|
47
|
-

|
|
48
|
-
|
|
49
|
-
## โจ Features
|
|
50
|
-
|
|
51
|
-
### Core Features
|
|
52
|
-
- ๐ **Framework Agnostic** - Works with any JavaScript framework or vanilla JS
|
|
53
|
-
- โฟ **Accessibility First** - WCAG AA compliant with screen reader support
|
|
54
|
-
- ๐ **Promise Lifecycle** - Automatic state transitions for async operations
|
|
55
|
-
- ๐ฑ **Mobile Optimized** - Touch gestures, swipe-to-dismiss, and responsive design
|
|
56
|
-
- ๐จ **Advanced Theming** - 13 built-in themes with CSS variables and custom themes
|
|
57
|
-
- ๐ **Plugin Architecture** - Extensible with custom plugins and hooks
|
|
58
|
-
- ๐ **Smart Queue Management** - Priority-based queuing with overflow strategies
|
|
59
|
-
- ๐ฏ **Rich Content Support** - HTML, icons, actions, progress bars, and custom rendering
|
|
60
|
-
- ๐ช **Spring Physics Animations** - Realistic animations with customizable physics parameters
|
|
61
|
-
- ๐๏ธ **SSR Safe** - Server-side rendering compatible
|
|
62
|
-
- ๐ช **Editor Integration** - Built-in hooks for rich text editors
|
|
63
|
-
- ๐ **Security** - HTML sanitization and XSS protection
|
|
64
|
-
- ๐ฆ **Zero Dependencies** - Lightweight and self-contained
|
|
65
|
-
|
|
66
|
-
### Advanced Features (v2.0.0)
|
|
67
|
-
- ๐ **Toast Updates** - Modify existing toasts dynamically with smooth transitions
|
|
68
|
-
- ๐ฏ **Toast Grouping** - Group related notifications with stacking and management
|
|
69
|
-
- ๐งฑ **Stacked Layouts** - Sonner-style collapsed stacks with hover/focus expansion
|
|
70
|
-
- ๐ **Title + Description API** - Modern content hierarchy for concise messages
|
|
71
|
-
- ๐ช **Custom Animation Hooks** - User-defined animation functions for complete control
|
|
72
|
-
- ๐ **Multiple Positions** - Support for all screen corners and center positioning
|
|
73
|
-
- ๐จ **Animation Manager** - Centralized system supporting CSS, spring, and custom animations
|
|
74
|
-
- ๐ฑ **Gesture Support** - Swipe and drag gestures for mobile interaction
|
|
75
|
-
- ๐ฏ **Focus Management** - Proper keyboard navigation and focus handling
|
|
76
|
-
- ๐ **Promise Integration** - Seamless integration with async operations and promises
|
|
77
|
-
- ๐ **Progress Tracking** - Built-in progress bars with percentage display
|
|
78
|
-
- ๐ฏ **Action Buttons** - Interactive buttons within toasts for user actions
|
|
79
|
-
- โฉ๏ธ **Action/Cancel Shortcuts** - First-class `action` and `cancel` options for undo flows
|
|
80
|
-
- ๐จ **Theme Variants** - Light, dark, system, colored, minimal, glass, neon, retro, ocean, forest, sunset, midnight themes
|
|
81
|
-
- ๐ง **Global Configuration** - Comprehensive configuration system for all aspects
|
|
82
|
-
- ๐งฉ **Headless State** - `subscribe()` and `getState()` for custom renderers and framework adapters
|
|
83
|
-
|
|
84
|
-
### Performance & Architecture
|
|
85
|
-
|
|
86
|
-
- โก **Optimized Queue Management** - O(1) insertion with priority-based queuing
|
|
87
|
-
- ๐ฏ **Batched DOM Updates** - Efficient rendering with minimal reflows
|
|
88
|
-
- ๐ง **Memory Safe** - Automatic cleanup and leak prevention
|
|
89
|
-
- ๐ **Virtualized Rendering** - Handles large queues without performance degradation
|
|
90
|
-
- ๐ **Event-Driven Architecture** - Plugin system with comprehensive hooks
|
|
91
|
-
- ๐ฆ **Tree-Shakable** - Import only what you need for smaller bundles
|
|
92
|
-
|
|
93
|
-
## ๐ฆ Installation
|
|
1
|
+
<h1 align="center">@editora/toast</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
Toast notifications with no dependencies and nothing to mount: call <code>toast.success('Saved')</code> from
|
|
5
|
+
anywhere. Status icons, a stack that opens on hover, promise toasts, actions, progress, light and dark, keyboard access.
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="https://www.npmjs.com/package/@editora/toast"><img src="https://img.shields.io/npm/v/@editora/toast.svg" alt="npm version"></a>
|
|
10
|
+
<a href="https://www.npmjs.com/package/@editora/toast"><img src="https://img.shields.io/npm/dm/@editora/toast.svg" alt="npm downloads"></a>
|
|
11
|
+
<a href="https://github.com/ajaykr089/Editora/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@editora/toast.svg" alt="license"></a>
|
|
12
|
+
<a href="https://www.npmjs.com/package/@editora/toast"><img src="https://img.shields.io/npm/types/@editora/toast.svg" alt="TypeScript types included"></a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://editora-ecosystem.netlify.app/toast-demo.html">Live demo</a> ยท
|
|
17
|
+
<a href="https://editora-ecosystem-storybook.netlify.app/">Storybook</a> ยท
|
|
18
|
+
<a href="https://github.com/ajaykr089/Editora">GitHub</a>
|
|
19
|
+
</p>
|
|
20
|
+
|
|
21
|
+
<p align="center">
|
|
22
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/themes.png" alt="Eleven toasts stacked in the top-right corner, one in each of the light, dark, colored, minimal, glass, neon, retro, ocean, forest, sunset and midnight themes" width="440">
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- **Nothing to mount.** No provider, no container element: the first call creates what it needs. It works from React,
|
|
28
|
+
Vue, plain JavaScript, a service, or an event handler.
|
|
29
|
+
- **A modern card.** An opaque, neutral surface with a status icon (a different shape for each level, so colour is
|
|
30
|
+
never the only cue), in light and dark. Dark follows the system, or your app's own `.dark` switch.
|
|
31
|
+
- **A stack that opens on hover.** Several toasts fold into a deck, the newest in full; hover it or focus it and it
|
|
32
|
+
opens into a list while the timers wait.
|
|
33
|
+
- **Promise toasts.** One toast follows a promise from *loading* to *success* or *error*.
|
|
34
|
+
- **Actions and progress**: buttons in the toast, and a progress bar with an optional percentage.
|
|
35
|
+
- **Thirteen themes and seven positions**, a queue (three toasts show at once by default), duplicate prevention and
|
|
36
|
+
swipe-to-dismiss.
|
|
37
|
+
- **Keyboard and screen readers.** Alt+T jumps to the toasts, Escape dismisses one, errors are announced as alerts and
|
|
38
|
+
the rest politely, and `prefers-reduced-motion` is respected.
|
|
39
|
+
- **Small.** 15 KB gzipped plus 5 KB of CSS. No dependencies.
|
|
40
|
+
- **Safe on the server.** The package imports in Node and the calls do nothing there, so a call in shared code does not
|
|
41
|
+
break server rendering.
|
|
42
|
+
- Written in TypeScript. A script tag works too (a UMD build).
|
|
43
|
+
|
|
44
|
+
## Install
|
|
94
45
|
|
|
95
46
|
```bash
|
|
96
47
|
npm install @editora/toast
|
|
97
48
|
```
|
|
98
49
|
|
|
99
|
-
##
|
|
50
|
+
## Quick start
|
|
100
51
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
### Basic CDN Setup
|
|
52
|
+
```ts
|
|
53
|
+
import { toast } from '@editora/toast';
|
|
54
|
+
import '@editora/toast/toast.css';
|
|
105
55
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
<meta charset="UTF-8">
|
|
111
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
112
|
-
<title>My App</title>
|
|
113
|
-
|
|
114
|
-
<!-- Include the CSS -->
|
|
115
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@editora/toast@latest/dist/toast.css">
|
|
116
|
-
</head>
|
|
117
|
-
<body>
|
|
118
|
-
<!-- Your content here -->
|
|
119
|
-
|
|
120
|
-
<!-- Include the JavaScript -->
|
|
121
|
-
<script src="https://cdn.jsdelivr.net/npm/@editora/toast@latest/dist/index.umd.js"></script>
|
|
122
|
-
|
|
123
|
-
<script>
|
|
124
|
-
// Now you can use the toast functions (legacy API supports an optional options object)
|
|
125
|
-
toast.success('Hello from CDN!', { theme: 'light', position: 'top-right' });
|
|
126
|
-
toast.error('Something went wrong!', { duration: 1000 });
|
|
127
|
-
toast.info('This is an info message', { theme: 'light', position: 'top-right' });
|
|
128
|
-
toast.warning('This is a warning', { theme: 'light', position: 'top-right' });
|
|
129
|
-
|
|
130
|
-
// Advanced usage (toastAdvanced, toastPro)
|
|
131
|
-
// global window.toastPro.show()
|
|
132
|
-
// global window.toastAdvanced.show()
|
|
133
|
-
const notification = toastAdvanced.show({
|
|
134
|
-
message: 'File uploaded successfully!',
|
|
135
|
-
level: 'success',
|
|
136
|
-
icon: 'โ',
|
|
137
|
-
actions: [
|
|
138
|
-
{ label: 'View', onClick: () => console.log('View clicked') },
|
|
139
|
-
{ label: 'Dismiss', onClick: () => notification.dismiss() }
|
|
140
|
-
]
|
|
141
|
-
});
|
|
142
|
-
const notification = toastPro.show({
|
|
143
|
-
message: 'File uploaded successfully!',
|
|
144
|
-
level: 'success',
|
|
145
|
-
icon: 'โ',
|
|
146
|
-
actions: [
|
|
147
|
-
{ label: 'View', onClick: () => console.log('View clicked') },
|
|
148
|
-
{ label: 'Dismiss', onClick: () => notification.dismiss() }
|
|
149
|
-
]
|
|
150
|
-
});
|
|
151
|
-
</script>
|
|
152
|
-
</body>
|
|
153
|
-
</html>
|
|
56
|
+
toast.success('Document saved');
|
|
57
|
+
toast.info('A new version is available');
|
|
58
|
+
toast.warning('Storage is almost full');
|
|
59
|
+
toast.error('Upload failed');
|
|
154
60
|
```
|
|
155
61
|
|
|
156
|
-
|
|
62
|
+
<p align="center">
|
|
63
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/levels.png" alt="Three toasts in the bottom-right corner, each with an icon: Document saved with a green check, A new version is available with a blue i and Storage is almost full with an orange warning triangle" width="440">
|
|
64
|
+
</p>
|
|
157
65
|
|
|
158
|
-
-
|
|
159
|
-
|
|
66
|
+
Toasts appear in the bottom-right corner and go away after four seconds. Three are visible at once; the rest wait in a
|
|
67
|
+
queue (a fourth toast, *Upload failed* above, appears when there is room). With more than one toast showing they fold
|
|
68
|
+
into a deck: see [Stacking](#stacking).
|
|
160
69
|
|
|
161
|
-
|
|
70
|
+
`toast` is all you need. Call it with a message for a plain toast, or use `toast.info`, `toast.success`,
|
|
71
|
+
`toast.warning`, `toast.error` and `toast.loading`, each taking a message and, if you like, an options object or a
|
|
72
|
+
duration in milliseconds. `toast.show`, `toast.promise`, `toast.update`, `toast.dismiss`, `toast.clear` and
|
|
73
|
+
`toast.configure` cover the rest. `toastAdvanced` (also exported as `toastPro`) is the same plus groups, plugins and
|
|
74
|
+
subscriptions.
|
|
162
75
|
|
|
163
|
-
##
|
|
76
|
+
## Titles, actions and progress
|
|
164
77
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
```typescript
|
|
78
|
+
```ts
|
|
168
79
|
import { toast } from '@editora/toast';
|
|
169
|
-
import
|
|
170
|
-
|
|
171
|
-
// Simple notifications (migrated to optional advanced options)
|
|
172
|
-
toast.success('File saved successfully!', { theme: 'light', position: 'top-right' });
|
|
173
|
-
toast.error('Failed to save file', { theme: 'light', position: 'top-right' });
|
|
174
|
-
toast.info('Info message', { theme: 'light', position: 'top-right' });
|
|
175
|
-
toast.warning('Warning message', { theme: 'light', position: 'top-right' });
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
### Advanced Usage (v2.0.0 Features)
|
|
80
|
+
import '@editora/toast/toast.css';
|
|
179
81
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
import "@editora/toast/toast.css";
|
|
183
|
-
// Rich notifications with actions and progress
|
|
184
|
-
const notification = toast.show({
|
|
185
|
-
message: 'Document uploaded successfully!',
|
|
82
|
+
// A toast with a title, a description, actions and progress. duration: 0 keeps it until it is dismissed.
|
|
83
|
+
const report = toast.show({
|
|
186
84
|
level: 'success',
|
|
187
|
-
|
|
85
|
+
title: 'Report ready',
|
|
86
|
+
description: 'Q3-summary.pdf is 2.4 MB',
|
|
188
87
|
actions: [
|
|
189
|
-
{ label: '
|
|
190
|
-
{ label: '
|
|
191
|
-
{ label: 'Dismiss', onClick: () => notification.dismiss() }
|
|
88
|
+
{ label: 'Open', primary: true, onClick: () => console.log('open') },
|
|
89
|
+
{ label: 'Dismiss', onClick: () => report.dismiss() }
|
|
192
90
|
],
|
|
193
|
-
|
|
194
|
-
duration: 6000
|
|
195
|
-
});
|
|
196
|
-
|
|
197
|
-
// Promise-based notifications with automatic state transitions
|
|
198
|
-
toast.promise(
|
|
199
|
-
uploadFile(file),
|
|
200
|
-
{
|
|
201
|
-
loading: 'Uploading file...',
|
|
202
|
-
success: (data) => `File "${data.name}" uploaded successfully!`,
|
|
203
|
-
error: (error) => `Upload failed: ${error.message}`
|
|
204
|
-
}
|
|
205
|
-
);
|
|
206
|
-
|
|
207
|
-
// Update existing toast dynamically
|
|
208
|
-
const loadingToast = toast.loading('Saving document...');
|
|
209
|
-
setTimeout(() => {
|
|
210
|
-
toast.update(loadingToast.id, {
|
|
211
|
-
message: 'Document saved successfully!',
|
|
212
|
-
level: 'success',
|
|
213
|
-
icon: '๐พ',
|
|
214
|
-
actions: [{ label: 'Open', onClick: () => {} }]
|
|
215
|
-
});
|
|
216
|
-
}, 2000);
|
|
217
|
-
|
|
218
|
-
// Group related notifications
|
|
219
|
-
toast.group('file-operations', {
|
|
220
|
-
message: 'File 1 processed',
|
|
221
|
-
level: 'success'
|
|
91
|
+
duration: 0
|
|
222
92
|
});
|
|
223
93
|
|
|
224
|
-
toast.
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
}
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
## ๐๏ธ Configuration
|
|
231
|
-
|
|
232
|
-
```typescript
|
|
233
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
234
|
-
import "@editora/toast/toast.css";
|
|
235
|
-
// Global configuration with all available options
|
|
236
|
-
toast.configure({
|
|
237
|
-
// Positioning
|
|
238
|
-
position: 'top-right', // 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center'
|
|
239
|
-
offset: 16,
|
|
240
|
-
mobileOffset: 16,
|
|
241
|
-
|
|
242
|
-
// Timing
|
|
243
|
-
duration: 5000, // Default duration in milliseconds
|
|
244
|
-
pauseOnHover: true, // Pause timer when hovering
|
|
245
|
-
pauseOnWindowBlur: true, // Pause timers when the tab/window is inactive
|
|
246
|
-
|
|
247
|
-
// Display
|
|
248
|
-
maxVisible: 3, // Maximum visible toasts
|
|
249
|
-
visibleToasts: 3, // Sonner-compatible alias
|
|
250
|
-
stack: false, // Set true to collapse visible toasts into a stack
|
|
251
|
-
expand: true, // Keep stacked toasts expanded by default
|
|
252
|
-
richColors: false, // Use semantic colored surfaces
|
|
253
|
-
closeButton: true, // Show close buttons globally
|
|
254
|
-
theme: 'system', // Theme: 'light' | 'dark' | 'system' | 'colored' | 'minimal' | 'glass' | 'neon' | 'retro' | 'ocean' | 'forest' | 'sunset' | 'midnight' | 'custom'
|
|
255
|
-
|
|
256
|
-
// Accessibility
|
|
257
|
-
enableAccessibility: true, // Enable screen reader support
|
|
258
|
-
|
|
259
|
-
// Interactions
|
|
260
|
-
swipeDismiss: true, // Enable swipe to dismiss on mobile
|
|
261
|
-
dragDismiss: false, // Enable drag to dismiss
|
|
262
|
-
|
|
263
|
-
// Queue Management
|
|
264
|
-
queueStrategy: 'fifo', // 'fifo' | 'lifo'
|
|
265
|
-
preventDuplicate: true,
|
|
266
|
-
dedupeScope: 'all', // 'visible' | 'queue' | 'all'
|
|
267
|
-
|
|
268
|
-
// Animations
|
|
269
|
-
animation: {
|
|
270
|
-
type: 'spring', // 'css' | 'spring' | 'custom'
|
|
271
|
-
config: {
|
|
272
|
-
stiffness: 120,
|
|
273
|
-
damping: 12,
|
|
274
|
-
mass: 1,
|
|
275
|
-
precision: 0.01
|
|
276
|
-
}
|
|
277
|
-
},
|
|
278
|
-
|
|
279
|
-
// Advanced
|
|
280
|
-
zIndex: 9999 // Base z-index for toasts
|
|
94
|
+
const upload = toast.show({
|
|
95
|
+
level: 'info',
|
|
96
|
+
message: 'Uploading photos',
|
|
97
|
+
progress: { value: 64, showPercentage: true },
|
|
98
|
+
duration: 0
|
|
281
99
|
});
|
|
282
100
|
```
|
|
283
101
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
102
|
+
<p align="center">
|
|
103
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/actions.png" alt="A toast titled Report ready with a description and Open and Dismiss buttons, under a toast that says Uploading photos with a progress bar at 64 percent" width="440">
|
|
104
|
+
</p>
|
|
287
105
|
|
|
288
|
-
|
|
106
|
+
`show()` returns the toast: `dismiss()` removes it and `update(options)` changes it. Pressing an action runs its `onClick`
|
|
107
|
+
and closes the toast; give the action `dismissOnClick: false` to keep the toast open. The progress bar follows
|
|
108
|
+
`update(id, { progress })`.
|
|
289
109
|
|
|
290
|
-
|
|
110
|
+
## Promises and updates
|
|
291
111
|
|
|
292
|
-
|
|
293
|
-
- **`dark`** - Dark background with high contrast text
|
|
294
|
-
- **`system`** - Automatically switches between light/dark based on system preference
|
|
295
|
-
- **`colored`** - Vibrant gradient backgrounds for each toast level
|
|
296
|
-
- **`minimal`** - Clean design with subtle borders and minimal styling
|
|
297
|
-
- **`glass`** - Frosted glass effect with backdrop blur
|
|
298
|
-
- **`neon`** - Bright neon colors with glowing effects
|
|
299
|
-
- **`retro`** - 80s/90s style with bold colors and gradients
|
|
300
|
-
- **`ocean`** - Blue aquatic theme with calming colors
|
|
301
|
-
- **`forest`** - Green natural theme with earthy tones
|
|
302
|
-
- **`sunset`** - Warm orange/pink sunset colors
|
|
303
|
-
- **`midnight`** - Deep blue dark theme with subtle gradients
|
|
304
|
-
- **`custom`** - Fully customizable with CSS variables
|
|
112
|
+
`toast.promise()` shows one toast that becomes the result of a promise, and `update()` changes any toast by id:
|
|
305
113
|
|
|
306
|
-
|
|
114
|
+
```ts
|
|
115
|
+
import { toast } from '@editora/toast';
|
|
116
|
+
import '@editora/toast/toast.css';
|
|
307
117
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
import "@editora/toast/toast.css";
|
|
311
|
-
// Set global theme
|
|
312
|
-
toast.configure({
|
|
313
|
-
theme: 'glass' // or 'neon', 'retro', 'ocean', etc.
|
|
118
|
+
const saveDocument = new Promise<{ name: string }>((resolve) => {
|
|
119
|
+
setTimeout(() => resolve({ name: 'Q3-summary.pdf' }), 1500);
|
|
314
120
|
});
|
|
315
121
|
|
|
316
|
-
//
|
|
317
|
-
toast.
|
|
318
|
-
|
|
319
|
-
|
|
122
|
+
// One toast that moves from loading to success or error by itself.
|
|
123
|
+
toast.promise(saveDocument, {
|
|
124
|
+
loading: 'Saving document...',
|
|
125
|
+
success: (file) => `Saved ${file.name}`,
|
|
126
|
+
error: (error) => `Could not save: ${error.message}`
|
|
320
127
|
});
|
|
321
|
-
```
|
|
322
128
|
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
:
|
|
327
|
-
|
|
328
|
-
--editora-toast-color: #fff;
|
|
329
|
-
--editora-toast-shadow: 0 6px 18px rgba(0, 0, 0, 0.25);
|
|
330
|
-
--editora-toast-border-radius: 6px;
|
|
331
|
-
--editora-toast-font-family: system-ui, -apple-system, 'Segoe UI', Roboto;
|
|
332
|
-
--editora-toast-font-size: 13px;
|
|
333
|
-
--editora-toast-padding: 10px 14px;
|
|
334
|
-
}
|
|
129
|
+
// Or update a toast yourself.
|
|
130
|
+
const sync = toast.loading('Syncing...');
|
|
131
|
+
setTimeout(() => {
|
|
132
|
+
toast.update(sync.id, { message: 'Everything is up to date', level: 'success' });
|
|
133
|
+
}, 2500);
|
|
335
134
|
```
|
|
336
135
|
|
|
337
|
-
|
|
136
|
+
<table>
|
|
137
|
+
<tr>
|
|
138
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/promise-loading.png" alt="Two toasts that read Saving document and Syncing, each with a spinner"></td>
|
|
139
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/promise-success.png" alt="The same toasts after the promise resolved and the update: Saved Q3-summary.pdf and Everything is up to date, each with a green check"></td>
|
|
140
|
+
</tr>
|
|
141
|
+
<tr>
|
|
142
|
+
<td align="center"><sub>While it works</sub></td>
|
|
143
|
+
<td align="center"><sub>After the promise resolves and the update</sub></td>
|
|
144
|
+
</tr>
|
|
145
|
+
</table>
|
|
338
146
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
<!-- All toasts will use glass theme -->
|
|
343
|
-
</div>
|
|
344
|
-
|
|
345
|
-
<!-- Or apply to specific container -->
|
|
346
|
-
<div class="editora-toast-container" data-theme="neon">
|
|
347
|
-
</div>
|
|
348
|
-
```
|
|
147
|
+
`toast.promise()` returns the promise you gave it, so you can still `await` it. If you only need the message, `success`
|
|
148
|
+
and `error` can be plain strings; they can also be options (`{ title, description, actions }`), which replace the
|
|
149
|
+
loading text.
|
|
349
150
|
|
|
350
|
-
##
|
|
351
|
-
|
|
352
|
-
### Promise Lifecycle Toasts
|
|
353
|
-

|
|
354
|
-
|
|
355
|
-
Automatically handle async operations with state transitions:
|
|
356
|
-
|
|
357
|
-
```typescript
|
|
358
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
359
|
-
|
|
360
|
-
// Promise-based notifications
|
|
361
|
-
const uploadPromise = uploadFile(file);
|
|
362
|
-
|
|
363
|
-
toast.promise(uploadPromise, {
|
|
364
|
-
loading: {
|
|
365
|
-
message: 'Uploading file...',
|
|
366
|
-
icon: 'โณ',
|
|
367
|
-
progress: { indeterminate: true }
|
|
368
|
-
},
|
|
369
|
-
success: {
|
|
370
|
-
message: 'File uploaded successfully!',
|
|
371
|
-
icon: 'โ
',
|
|
372
|
-
duration: 4000,
|
|
373
|
-
actions: [{ label: 'View', onClick: () => openFile() }]
|
|
374
|
-
},
|
|
375
|
-
error: {
|
|
376
|
-
message: 'Upload failed. Please try again.',
|
|
377
|
-
icon: 'โ',
|
|
378
|
-
duration: 6000,
|
|
379
|
-
actions: [
|
|
380
|
-
{ label: 'Retry', onClick: () => retryUpload() },
|
|
381
|
-
{ label: 'Cancel', onClick: () => {} }
|
|
382
|
-
]
|
|
383
|
-
}
|
|
384
|
-
});
|
|
385
|
-
```
|
|
151
|
+
## Stacking
|
|
386
152
|
|
|
387
|
-
|
|
388
|
-
|
|
153
|
+
```ts
|
|
154
|
+
import { toast } from '@editora/toast';
|
|
155
|
+
import '@editora/toast/toast.css';
|
|
389
156
|
|
|
390
|
-
|
|
157
|
+
// By default several toasts fold into a deck: the newest in full, the others as edges behind it.
|
|
158
|
+
// Hover the deck (or press Alt+T) and it opens into a list; the timers wait while it is open.
|
|
159
|
+
toast.success('Document saved');
|
|
160
|
+
toast.info('A new version is available');
|
|
161
|
+
toast.warning('Storage is almost full');
|
|
391
162
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
import "@editora/toast/toast.css";
|
|
395
|
-
const notification = toast.show({
|
|
396
|
-
message: 'Document saved successfully!',
|
|
397
|
-
level: 'success',
|
|
398
|
-
icon: '๐พ',
|
|
399
|
-
actions: [
|
|
400
|
-
{
|
|
401
|
-
label: 'Open Document',
|
|
402
|
-
onClick: () => openDocument(),
|
|
403
|
-
primary: true // Primary action styling
|
|
404
|
-
},
|
|
405
|
-
{
|
|
406
|
-
label: 'Share',
|
|
407
|
-
onClick: () => shareDocument(),
|
|
408
|
-
variant: 'secondary'
|
|
409
|
-
},
|
|
410
|
-
{
|
|
411
|
-
label: 'Dismiss',
|
|
412
|
-
onClick: () => notification.dismiss(),
|
|
413
|
-
variant: 'ghost'
|
|
414
|
-
}
|
|
415
|
-
],
|
|
416
|
-
duration: 8000 // Longer duration for actions
|
|
417
|
-
});
|
|
163
|
+
// Prefer a plain list that is always open?
|
|
164
|
+
// toast.configure({ stack: false });
|
|
418
165
|
```
|
|
419
166
|
|
|
420
|
-
|
|
421
|
-
|
|
167
|
+
<table>
|
|
168
|
+
<tr>
|
|
169
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/deck-closed.png" alt="Three toasts folded into a deck: Storage is almost full in front, with the edges of the two older toasts behind it"></td>
|
|
170
|
+
<td><img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/deck-open.png" alt="The same toasts opened into a list, the newest nearest the corner"></td>
|
|
171
|
+
</tr>
|
|
172
|
+
<tr>
|
|
173
|
+
<td align="center"><sub>Folded</sub></td>
|
|
174
|
+
<td align="center"><sub>Hovered or focused</sub></td>
|
|
175
|
+
</tr>
|
|
176
|
+
</table>
|
|
422
177
|
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
427
|
-
import "@editora/toast/toast.css";
|
|
428
|
-
// Determinate progress
|
|
429
|
-
const progressToast = toast.show({
|
|
430
|
-
message: 'Processing files...',
|
|
431
|
-
level: 'info',
|
|
432
|
-
progress: {
|
|
433
|
-
value: 0,
|
|
434
|
-
showPercentage: true,
|
|
435
|
-
color: '#007acc'
|
|
436
|
-
}
|
|
437
|
-
});
|
|
178
|
+
The newest toast is always the one nearest the edge of the screen. While the deck is open, the timers of its toasts wait,
|
|
179
|
+
and a toast that arrives meanwhile waits with them. A toast that is dismissed leaves at once and the others close the gap.
|
|
180
|
+
`stack: false` keeps a plain list; `stack: true, expand: true` shows a list that is always open.
|
|
438
181
|
|
|
439
|
-
|
|
440
|
-
let progress = 0;
|
|
441
|
-
const interval = setInterval(() => {
|
|
442
|
-
progress += 10;
|
|
443
|
-
toast.update(progressToast.id, {
|
|
444
|
-
progress: { value: progress, showPercentage: true },
|
|
445
|
-
message: `Processing files... ${progress}%`
|
|
446
|
-
});
|
|
447
|
-
|
|
448
|
-
if (progress >= 100) {
|
|
449
|
-
clearInterval(interval);
|
|
450
|
-
toast.update(progressToast.id, {
|
|
451
|
-
message: 'Processing complete!',
|
|
452
|
-
level: 'success',
|
|
453
|
-
progress: { value: 100, showPercentage: true }
|
|
454
|
-
});
|
|
455
|
-
}
|
|
456
|
-
}, 500);
|
|
457
|
-
```
|
|
182
|
+
On a touch screen a tap opens the deck; a tap elsewhere closes it.
|
|
458
183
|
|
|
459
|
-
|
|
460
|
-

|
|
184
|
+
## Icons
|
|
461
185
|
|
|
462
|
-
|
|
186
|
+
```ts
|
|
187
|
+
import { toast } from '@editora/toast';
|
|
188
|
+
import '@editora/toast/toast.css';
|
|
463
189
|
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
import "@editora/toast/toast.css";
|
|
467
|
-
// Create a loading toast
|
|
468
|
-
const loadingToast = toast.loading('Connecting to server...');
|
|
190
|
+
// A list instead of a deck, so all four are visible at once.
|
|
191
|
+
toast.configure({ maxVisible: 4, stack: false });
|
|
469
192
|
|
|
470
|
-
//
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
progress: { value: 25, showPercentage: true }
|
|
475
|
-
});
|
|
476
|
-
}, 1000);
|
|
193
|
+
toast.success('Saved'); // the icon of the level
|
|
194
|
+
toast('Copied to clipboard'); // no level, no icon
|
|
195
|
+
toast.info('Invite sent', { icon: 'โ๏ธ' }); // your own: text, an emoji or a DOM node
|
|
196
|
+
toast.error('Payment failed', { icon: false }); // none
|
|
477
197
|
|
|
478
|
-
//
|
|
479
|
-
|
|
480
|
-
toast.update(loadingToast.id, {
|
|
481
|
-
message: 'Connected successfully!',
|
|
482
|
-
level: 'success',
|
|
483
|
-
icon: '๐',
|
|
484
|
-
progress: { value: 100, showPercentage: true },
|
|
485
|
-
actions: [{ label: 'Explore', onClick: () => {} }]
|
|
486
|
-
});
|
|
487
|
-
}, 2000);
|
|
198
|
+
// Or switch the built-in icons off everywhere:
|
|
199
|
+
// toast.configure({ icons: false });
|
|
488
200
|
```
|
|
489
201
|
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
Group related notifications together:
|
|
202
|
+
<p align="center">
|
|
203
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/icons.png" alt="Four toasts: Saved with a green check, Copied to clipboard without an icon, Invite sent with an envelope emoji and Payment failed without an icon" width="440">
|
|
204
|
+
</p>
|
|
494
205
|
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
import "@editora/toast/toast.css";
|
|
498
|
-
// Group file operations
|
|
499
|
-
const files = ['document.pdf', 'image.jpg', 'data.json'];
|
|
500
|
-
|
|
501
|
-
files.forEach((file, index) => {
|
|
502
|
-
setTimeout(() => {
|
|
503
|
-
toast.group('file-upload', {
|
|
504
|
-
message: `Uploaded ${file}`,
|
|
505
|
-
level: 'success',
|
|
506
|
-
icon: '๐',
|
|
507
|
-
duration: 3000
|
|
508
|
-
});
|
|
509
|
-
}, index * 500);
|
|
510
|
-
});
|
|
206
|
+
The built-in icons are drawn in SVG from the level's colour (`--et-success`, `--et-error`, ...) and are hidden from screen
|
|
207
|
+
readers; the message carries the meaning. `icon` takes a string (text or an emoji), a DOM node, or `false`.
|
|
511
208
|
|
|
512
|
-
|
|
513
|
-
toast.group('validation-errors', {
|
|
514
|
-
message: 'Invalid email format',
|
|
515
|
-
level: 'error',
|
|
516
|
-
icon: 'โ ๏ธ'
|
|
517
|
-
});
|
|
209
|
+
## In React, and in any framework
|
|
518
210
|
|
|
519
|
-
toast
|
|
520
|
-
message: 'Password too weak',
|
|
521
|
-
level: 'error',
|
|
522
|
-
icon: '๐'
|
|
523
|
-
});
|
|
524
|
-
```
|
|
211
|
+
There is nothing to render. Call `toast` from a handler, an effect or a service:
|
|
525
212
|
|
|
526
|
-
|
|
527
|
-
|
|
213
|
+
```tsx
|
|
214
|
+
import { toast } from '@editora/toast';
|
|
215
|
+
import '@editora/toast/toast.css';
|
|
528
216
|
|
|
529
|
-
|
|
217
|
+
async function saveDraft() {
|
|
218
|
+
await new Promise((resolve) => setTimeout(resolve, 800));
|
|
219
|
+
return { name: 'draft.md' };
|
|
220
|
+
}
|
|
530
221
|
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
<div style="display: flex; gap: 8px; margin-top: 8px;">
|
|
542
|
-
<button class="feedback-btn" data-rating="1">๐</button>
|
|
543
|
-
<button class="feedback-btn" data-rating="2">๐</button>
|
|
544
|
-
<button class="feedback-btn" data-rating="3">๐</button>
|
|
545
|
-
<button class="feedback-btn" data-rating="4">๐</button>
|
|
546
|
-
<button class="feedback-btn" data-rating="5">๐</button>
|
|
547
|
-
</div>
|
|
548
|
-
`;
|
|
549
|
-
|
|
550
|
-
container.addEventListener('click', (e) => {
|
|
551
|
-
if (e.target.classList.contains('feedback-btn')) {
|
|
552
|
-
const rating = e.target.dataset.rating;
|
|
553
|
-
submitFeedback(rating);
|
|
554
|
-
toast.success('Thank you for your feedback!');
|
|
222
|
+
// There is nothing to mount: call toast from any handler or effect.
|
|
223
|
+
export default function SaveButton() {
|
|
224
|
+
return (
|
|
225
|
+
<button
|
|
226
|
+
onClick={() =>
|
|
227
|
+
toast.promise(saveDraft(), {
|
|
228
|
+
loading: 'Saving...',
|
|
229
|
+
success: (file) => `Saved ${file.name}`,
|
|
230
|
+
error: 'Could not save'
|
|
231
|
+
})
|
|
555
232
|
}
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
});
|
|
233
|
+
>
|
|
234
|
+
Save
|
|
235
|
+
</button>
|
|
236
|
+
);
|
|
237
|
+
}
|
|
562
238
|
```
|
|
563
239
|
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
```typescript
|
|
567
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
568
|
-
import "@editora/toast/toast.css";
|
|
569
|
-
const myPlugin = {
|
|
570
|
-
name: 'my-plugin',
|
|
571
|
-
install(manager) {
|
|
572
|
-
// Add custom functionality
|
|
573
|
-
manager.on('beforeShow', (toast) => {
|
|
574
|
-
console.log('Toast about to show:', toast.message);
|
|
575
|
-
});
|
|
576
|
-
}
|
|
577
|
-
};
|
|
240
|
+
[`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) also has a `ToastProvider` and a `useToast()` hook
|
|
241
|
+
if you like a provider.
|
|
578
242
|
|
|
579
|
-
|
|
580
|
-
```
|
|
243
|
+
## From a script tag
|
|
581
244
|
|
|
582
|
-
|
|
245
|
+
The UMD build defines three globals: `toast`, `toastAdvanced` and `toastPro` (the same object as `toastAdvanced`).
|
|
246
|
+
Pin a version in production, as here:
|
|
583
247
|
|
|
584
|
-
```
|
|
585
|
-
toast.
|
|
586
|
-
|
|
587
|
-
position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center'
|
|
588
|
-
});
|
|
589
|
-
```
|
|
248
|
+
```html
|
|
249
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@editora/toast@2/dist/toast.css" />
|
|
250
|
+
<script src="https://cdn.jsdelivr.net/npm/@editora/toast@2/dist/index.umd.js"></script>
|
|
590
251
|
|
|
591
|
-
|
|
252
|
+
<button id="save">Save</button>
|
|
592
253
|
|
|
593
|
-
|
|
254
|
+
<script>
|
|
255
|
+
document.getElementById('save').onclick = () => {
|
|
256
|
+
// The script defines three globals: toast, toastAdvanced and toastPro (the same object as toastAdvanced).
|
|
257
|
+
toast.success('Saved from a CDN');
|
|
594
258
|
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
damping: 12, // Spring damping (default: 10)
|
|
607
|
-
mass: 1, // Spring mass (default: 1)
|
|
608
|
-
precision: 0.01 // Animation precision (default: 0.01)
|
|
609
|
-
}
|
|
610
|
-
}
|
|
611
|
-
});
|
|
259
|
+
const notification = toastAdvanced.show({
|
|
260
|
+
message: 'File uploaded',
|
|
261
|
+
level: 'success',
|
|
262
|
+
actions: [
|
|
263
|
+
{ label: 'View', onClick: () => console.log('view') },
|
|
264
|
+
{ label: 'Dismiss', onClick: () => notification.dismiss() }
|
|
265
|
+
],
|
|
266
|
+
duration: 0
|
|
267
|
+
});
|
|
268
|
+
};
|
|
269
|
+
</script>
|
|
612
270
|
```
|
|
613
271
|
|
|
614
|
-
|
|
272
|
+
## Configure it
|
|
615
273
|
|
|
616
|
-
|
|
617
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
618
|
-
import "@editora/toast/toast.css";
|
|
619
|
-
// Custom animation functions
|
|
620
|
-
toast.show({
|
|
621
|
-
message: 'Custom animated toast!',
|
|
622
|
-
level: 'info',
|
|
623
|
-
animation: {
|
|
624
|
-
type: 'custom',
|
|
625
|
-
show: async (element, toast) => {
|
|
626
|
-
// Custom show animation
|
|
627
|
-
element.style.opacity = '0';
|
|
628
|
-
element.style.transform = 'rotateX(90deg)';
|
|
629
|
-
|
|
630
|
-
await new Promise(resolve => {
|
|
631
|
-
element.style.transition = 'all 0.5s ease';
|
|
632
|
-
element.style.opacity = '1';
|
|
633
|
-
element.style.transform = 'rotateX(0deg)';
|
|
634
|
-
element.addEventListener('transitionend', resolve, { once: true });
|
|
635
|
-
});
|
|
636
|
-
},
|
|
637
|
-
hide: async (element, toast) => {
|
|
638
|
-
// Custom hide animation
|
|
639
|
-
element.style.transition = 'all 0.3s ease';
|
|
640
|
-
element.style.opacity = '0';
|
|
641
|
-
element.style.transform = 'scale(0.8)';
|
|
642
|
-
|
|
643
|
-
return new Promise(resolve => {
|
|
644
|
-
setTimeout(resolve, 300);
|
|
645
|
-
});
|
|
646
|
-
},
|
|
647
|
-
update: async (element, toast, updates) => {
|
|
648
|
-
// Custom update animation
|
|
649
|
-
element.style.transform = 'scale(1.05)';
|
|
650
|
-
setTimeout(() => {
|
|
651
|
-
element.style.transform = 'scale(1)';
|
|
652
|
-
}, 150);
|
|
653
|
-
}
|
|
654
|
-
}
|
|
655
|
-
});
|
|
656
|
-
```
|
|
274
|
+
`configure()` sets the defaults for every toast from then on. A single toast can still override them:
|
|
657
275
|
|
|
658
|
-
|
|
276
|
+
```ts
|
|
277
|
+
import { toast } from '@editora/toast';
|
|
278
|
+
import '@editora/toast/toast.css';
|
|
659
279
|
|
|
660
|
-
|
|
661
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
662
|
-
import "@editora/toast/toast.css";
|
|
663
|
-
// Set default animation for all toasts
|
|
280
|
+
// Settings for every toast from now on. A toast can still override them.
|
|
664
281
|
toast.configure({
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
### Toast Groups
|
|
673
|
-
|
|
674
|
-
```typescript
|
|
675
|
-
// Group related notifications
|
|
676
|
-
toast.group('upload-group', {
|
|
677
|
-
message: 'Upload 1 complete',
|
|
678
|
-
level: 'success'
|
|
679
|
-
});
|
|
680
|
-
|
|
681
|
-
toast.group('upload-group', {
|
|
682
|
-
message: 'Upload 2 complete',
|
|
683
|
-
level: 'success'
|
|
684
|
-
});
|
|
685
|
-
```
|
|
686
|
-
|
|
687
|
-
### Rich Text (`html: true`)
|
|
688
|
-
|
|
689
|
-
Messages are plain text by default. Set `html: true` to render a **safe subset** of HTML: inline formatting
|
|
690
|
-
(`b`, `strong`, `i`, `em`, `u`, `s`, `del`, `ins`, `mark`, `small`, `sub`, `sup`, `code`, `kbd`, `span`), `br`, `p`,
|
|
691
|
-
lists (`ul`, `ol`, `li`) and links. Links keep only `http(s):`, `mailto:`, `tel:` and relative URLs; external links
|
|
692
|
-
open in a new tab with `rel="noopener noreferrer"`. Everything else (scripts, event handlers, `style`, images,
|
|
693
|
-
iframes, forms...) is removed, and unknown elements are unwrapped so their text stays.
|
|
694
|
-
|
|
695
|
-
```typescript
|
|
696
|
-
toast.success('Saved <b>3</b> files. <a href="/reports">View report</a>', { html: true });
|
|
697
|
-
```
|
|
698
|
-
|
|
699
|
-
`title`, `description`, `icon` and action labels are always plain text. For anything richer, use `render`.
|
|
700
|
-
|
|
701
|
-
### Dismissing Persistent Toasts
|
|
702
|
-
|
|
703
|
-
A toast with `duration: 0` (or `persistent: true`) stays until it is dismissed, so give it a way out: pass
|
|
704
|
-
`closeButton: true` (alias `closable: true`), add an action, or keep the returned instance and call `dismiss()`.
|
|
705
|
-
On pointer devices the close button fades in on hover or keyboard focus; on touch devices it is always visible.
|
|
706
|
-
|
|
707
|
-
### Custom Render Function
|
|
708
|
-
|
|
709
|
-
```typescript
|
|
710
|
-
toast.show({
|
|
711
|
-
render: () => {
|
|
712
|
-
const div = document.createElement('div');
|
|
713
|
-
div.innerHTML = '<strong>Custom</strong> content';
|
|
714
|
-
return div;
|
|
715
|
-
}
|
|
282
|
+
position: 'top-center',
|
|
283
|
+
duration: 6000,
|
|
284
|
+
maxVisible: 3,
|
|
285
|
+
theme: 'ocean',
|
|
286
|
+
closeButton: true,
|
|
287
|
+
preventDuplicate: true
|
|
716
288
|
});
|
|
717
|
-
```
|
|
718
|
-
|
|
719
|
-
### Editor Integration
|
|
720
289
|
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
// Listen for editor events
|
|
725
|
-
toast.onEditorEvent('spellcheck-error', (error) => {
|
|
726
|
-
toast.error(`Spelling error: ${error.word}`, { theme: 'light', position: 'top-right' });
|
|
727
|
-
});
|
|
728
|
-
|
|
729
|
-
// Trigger editor events
|
|
730
|
-
toast.triggerEditorEvent('media-upload-progress', { progress: 50 });
|
|
290
|
+
toast.info('Welcome back');
|
|
291
|
+
toast.info('Welcome back'); // the duplicate is dropped
|
|
292
|
+
toast.warning('Your plan renews tomorrow', { theme: 'sunset', duration: 0 });
|
|
731
293
|
```
|
|
732
294
|
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
```typescript
|
|
764
|
-
interface ToastOptions {
|
|
765
|
-
// Content
|
|
766
|
-
message?: string;
|
|
767
|
-
title?: string;
|
|
768
|
-
description?: string;
|
|
769
|
-
level?: 'info' | 'success' | 'error' | 'warning' | 'loading' | 'progress' | 'promise' | 'custom';
|
|
770
|
-
icon?: string;
|
|
771
|
-
html?: boolean; // render `message` as safe HTML (see "Rich Text" above)
|
|
772
|
-
render?: (toast: ToastInstance) => HTMLElement;
|
|
773
|
-
|
|
774
|
-
// Behavior
|
|
775
|
-
duration?: number;
|
|
776
|
-
pauseOnHover?: boolean;
|
|
777
|
-
persistent?: boolean;
|
|
778
|
-
closeButton?: boolean; // show a close button (alias: closable)
|
|
779
|
-
|
|
780
|
-
// Positioning
|
|
781
|
-
position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center';
|
|
782
|
-
|
|
783
|
-
// Interactions
|
|
784
|
-
actions?: ToastAction[];
|
|
785
|
-
action?: ToastAction;
|
|
786
|
-
cancel?: ToastAction;
|
|
787
|
-
swipeDismiss?: boolean;
|
|
788
|
-
dragDismiss?: boolean;
|
|
789
|
-
|
|
790
|
-
// Progress
|
|
791
|
-
progress?: ToastProgress;
|
|
792
|
-
|
|
793
|
-
// Styling
|
|
794
|
-
theme?: string;
|
|
795
|
-
customClass?: string;
|
|
796
|
-
|
|
797
|
-
// Advanced
|
|
798
|
-
group?: string;
|
|
799
|
-
priority?: number;
|
|
800
|
-
important?: boolean;
|
|
801
|
-
preventDuplicate?: boolean;
|
|
802
|
-
dedupeKey?: string;
|
|
803
|
-
dedupeScope?: 'visible' | 'queue' | 'all';
|
|
804
|
-
ariaLive?: 'polite' | 'assertive' | 'off';
|
|
805
|
-
animation?: ToastAnimation;
|
|
806
|
-
onShow?: () => void;
|
|
807
|
-
onHide?: () => void;
|
|
808
|
-
onUpdate?: (updates: Partial<ToastOptions>) => void;
|
|
809
|
-
}
|
|
295
|
+
| Setting | Default | |
|
|
296
|
+
| --- | --- | --- |
|
|
297
|
+
| `position` | `'bottom-right'` | Where toasts appear (see [Positions](#positions)). |
|
|
298
|
+
| `duration` | `4000` | How long a toast stays, in milliseconds. `0` keeps it until it is dismissed. |
|
|
299
|
+
| `maxVisible` | `3` | How many show at once; the others wait in the queue. (`visibleToasts` is an alias.) |
|
|
300
|
+
| `queueStrategy` | `'fifo'` | `'fifo'` or `'lifo'`: which waiting toast comes next. |
|
|
301
|
+
| `theme` | `'system'` | One of the [themes](#themes). |
|
|
302
|
+
| `closeButton` | `false` | Show a close button on every toast. |
|
|
303
|
+
| `icons` | `true` | Show the built-in status icons. |
|
|
304
|
+
| `preventDuplicate` | `false` | Drop a toast whose content is already showing. With `dedupeScope`: `'visible'`, `'queue'` or `'all'` (the default). |
|
|
305
|
+
| `stack`, `expand`, `gap` | `true`, `false`, `8` | A deck that opens on hover (`stack`), a list that is always open (`expand`, or `stack: false`), and the gap between toasts. |
|
|
306
|
+
| `pauseOnHover`, `pauseOnFocus`, `pauseOnWindowBlur` | `true`, `true`, `false` | Hold the timers while the pointer is over the stack, a toast has keyboard focus, or the window is in the background. The time that was left is kept. |
|
|
307
|
+
| `hotkey` | `'alt+t'` | A shortcut that moves focus to the toasts, for example `'ctrl+shift+k'`; `false` turns it off. |
|
|
308
|
+
| `swipeDismiss`, `swipeDirection`, `dragDismiss` | `true`, `'any'`, `false` | Dismiss by swiping, in which direction, and by dragging. |
|
|
309
|
+
| `offset`, `mobileOffset`, `zIndex` | `16`, `16`, none | The distance from the edge of the screen, on desktop and on mobile, and the stacking order. |
|
|
310
|
+
| `rtl` | `false` | Right-to-left layout. |
|
|
311
|
+
| `richColors` | `false` | Tint each toast with the colour of its level. |
|
|
312
|
+
| `container` | the page body | The element toasts are added to. |
|
|
313
|
+
|
|
314
|
+
`toast.getConfig()` (on `toastAdvanced`) returns the current settings.
|
|
315
|
+
|
|
316
|
+
## Themes
|
|
317
|
+
|
|
318
|
+
`light`, `dark`, `system`, `colored`, `minimal`, `glass`, `neon`, `retro`, `ocean`, `forest`, `sunset`, `midnight` and
|
|
319
|
+
`custom`. Set one for all toasts with `configure({ theme })`, or for one toast with `{ theme }`:
|
|
320
|
+
|
|
321
|
+
```ts
|
|
322
|
+
import { toast } from '@editora/toast';
|
|
323
|
+
import '@editora/toast/toast.css';
|
|
810
324
|
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
onClick: () => void;
|
|
814
|
-
primary?: boolean;
|
|
815
|
-
dismissOnClick?: boolean;
|
|
816
|
-
altText?: string;
|
|
817
|
-
}
|
|
325
|
+
// A deck would fold these into one; stack: false keeps them in a list.
|
|
326
|
+
toast.configure({ position: 'top-right', maxVisible: 12, stack: false, gap: 8 });
|
|
818
327
|
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
}
|
|
328
|
+
const themes = [
|
|
329
|
+
'light', 'dark', 'colored', 'minimal', 'glass', 'neon', 'retro', 'ocean', 'forest', 'sunset', 'midnight'
|
|
330
|
+
] as const;
|
|
823
331
|
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
config?: SpringConfig;
|
|
827
|
-
show?: AnimationFunction;
|
|
828
|
-
hide?: AnimationFunction;
|
|
829
|
-
update?: AnimationFunction;
|
|
332
|
+
for (const theme of themes) {
|
|
333
|
+
toast.info(`The ${theme} theme`, { theme, duration: 0 });
|
|
830
334
|
}
|
|
831
335
|
```
|
|
832
336
|
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
```bash
|
|
838
|
-
# Clone the repository
|
|
839
|
-
git clone https://github.com/ajaykr089/Editora.git
|
|
840
|
-
cd Editora/packages/editora-toast
|
|
841
|
-
|
|
842
|
-
# Install dependencies
|
|
843
|
-
npm install
|
|
844
|
-
|
|
845
|
-
# Start the standalone CodeSandbox-ready example
|
|
846
|
-
cd ../../examples/editora-toast
|
|
847
|
-
npm install
|
|
848
|
-
npm run dev
|
|
849
|
-
```
|
|
850
|
-
|
|
851
|
-
The demo showcases:
|
|
852
|
-
- โ
All 13 built-in themes
|
|
853
|
-
- ๐ฏ Interactive actions and buttons
|
|
854
|
-
- ๐ Progress bars and indicators
|
|
855
|
-
- ๐ Promise lifecycle management
|
|
856
|
-
- ๐ช Spring physics animations
|
|
857
|
-
- ๐ฑ Mobile gestures and touch support
|
|
858
|
-
- โฟ Accessibility features
|
|
859
|
-
- ๐จ Custom rendering and HTML content
|
|
860
|
-
- ๐ฑ Responsive design across devices
|
|
337
|
+
The picture at the top of this page is that code. `system` (the default) follows the operating system's light or dark
|
|
338
|
+
setting, and your app's own switch: a `dark` class, or `data-theme="dark"`, `data-bs-theme="dark"`,
|
|
339
|
+
`data-color-scheme="dark"` or `data-mantine-color-scheme="dark"` on the `<html>` element (and `light` for an app that is
|
|
340
|
+
light while the system is dark). Each toast carries `data-theme` and level classes (`editora-toast-info`, ...).
|
|
861
341
|
|
|
862
|
-
|
|
342
|
+
A theme is a set of CSS variables, so you can make your own with a few lines (the `custom` theme leaves the colours to you):
|
|
863
343
|
|
|
864
|
-
```
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
#
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
# Clean
|
|
875
|
-
npm run clean
|
|
344
|
+
```css
|
|
345
|
+
.editora-toast[data-theme="custom"] {
|
|
346
|
+
--et-bg: #fffbeb;
|
|
347
|
+
--et-text: #292524;
|
|
348
|
+
--et-text-muted: #78716c;
|
|
349
|
+
--et-border: #fcd34d;
|
|
350
|
+
--et-success: #15803d; /* the colour of the success icon; also --et-error, --et-warning, --et-info, --et-loading */
|
|
351
|
+
--et-radius: 16px;
|
|
352
|
+
}
|
|
876
353
|
```
|
|
877
354
|
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
- Chrome 60+
|
|
881
|
-
- Firefox 55+
|
|
882
|
-
- Safari 12+
|
|
883
|
-
- Edge 79+
|
|
884
|
-
|
|
885
|
-
## ๐ License
|
|
886
|
-
|
|
887
|
-
MIT ยฉ [Ajay Kumar](https://github.com/ajaykr089)
|
|
888
|
-
|
|
889
|
-
## ๐ค Contributing
|
|
890
|
-
|
|
891
|
-
Contributions welcome! Please see the [main repository](https://github.com/ajaykr089/Editora) for contribution guidelines.
|
|
892
|
-
|
|
893
|
-
## ๐ Migration Guide
|
|
355
|
+
`--et-width`, `--et-font`, `--et-shadow`, `--et-action-bg` and `--et-action-ink` (the primary button) are variables too.
|
|
894
356
|
|
|
895
|
-
|
|
357
|
+
## Positions
|
|
896
358
|
|
|
897
|
-
|
|
359
|
+
`top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right` and `center`:
|
|
898
360
|
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
```typescript
|
|
902
|
-
// v1.x (still works)
|
|
361
|
+
```ts
|
|
903
362
|
import { toast } from '@editora/toast';
|
|
904
|
-
import
|
|
905
|
-
toast.success('Hello World', { theme: 'light', position: 'top-right' });
|
|
906
|
-
|
|
907
|
-
// v2.0.0 advanced features
|
|
908
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
909
|
-
import "@editora/toast/toast.css";
|
|
910
|
-
// Promise lifecycle toasts
|
|
911
|
-
toast.promise(fetchData(), {
|
|
912
|
-
loading: 'Loading...',
|
|
913
|
-
success: 'Data loaded!',
|
|
914
|
-
error: 'Failed to load'
|
|
915
|
-
});
|
|
363
|
+
import '@editora/toast/toast.css';
|
|
916
364
|
|
|
917
|
-
|
|
918
|
-
toast.show({
|
|
919
|
-
message: 'File uploaded!',
|
|
920
|
-
level: 'success',
|
|
921
|
-
icon: 'โ
',
|
|
922
|
-
actions: [
|
|
923
|
-
{ label: 'View', onClick: () => {} },
|
|
924
|
-
{ label: 'Share', onClick: () => {} }
|
|
925
|
-
],
|
|
926
|
-
progress: { value: 100, showPercentage: true }
|
|
927
|
-
});
|
|
365
|
+
toast.configure({ maxVisible: 10 });
|
|
928
366
|
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
367
|
+
const positions = [
|
|
368
|
+
'top-left', 'top-center', 'top-right',
|
|
369
|
+
'bottom-left', 'bottom-center', 'bottom-right',
|
|
370
|
+
'center'
|
|
371
|
+
] as const;
|
|
932
372
|
|
|
933
|
-
|
|
934
|
-
toast.
|
|
935
|
-
|
|
373
|
+
for (const position of positions) {
|
|
374
|
+
toast.success(position, { position, duration: 0 });
|
|
375
|
+
}
|
|
936
376
|
```
|
|
937
377
|
|
|
938
|
-
|
|
378
|
+
<p align="center">
|
|
379
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/positions.png" alt="Seven toasts on a page: one at each corner, one at the top centre, one at the bottom centre and one in the middle" width="900">
|
|
380
|
+
</p>
|
|
381
|
+
|
|
382
|
+
## Toast options
|
|
383
|
+
|
|
384
|
+
Everything `show()` accepts. All of it is optional except a message (or a title):
|
|
385
|
+
|
|
386
|
+
| Option | |
|
|
387
|
+
| --- | --- |
|
|
388
|
+
| `message`, `title`, `description` | The text. |
|
|
389
|
+
| `level` | `'info'`, `'success'`, `'warning'`, `'error'` or `'loading'`. |
|
|
390
|
+
| `icon` | Your own icon: a string (text or an emoji) or a DOM node; `false` for none. Left out, the level's icon. |
|
|
391
|
+
| `actions`, `action`, `cancel` | Buttons: `{ label, onClick, primary?, dismissOnClick? }`. |
|
|
392
|
+
| `progress` | `{ value, showPercentage? }`, with `value` from 0 to 100. |
|
|
393
|
+
| `duration`, `persistent` | How long it stays (`0`, or `persistent: true`, keeps it until dismissed). |
|
|
394
|
+
| `position`, `theme`, `customClass`, `rtl` | Where it appears and how it looks. |
|
|
395
|
+
| `closable` / `closeButton` | Show a close button. |
|
|
396
|
+
| `html` | Render `message` as HTML. Only inline formatting, lists and safe links are kept. |
|
|
397
|
+
| `render` | Build the toast yourself: `(toast) => HTMLElement`. |
|
|
398
|
+
| `priority`, `important` | Show higher priorities first; `important` also pushes lower-priority toasts out. |
|
|
399
|
+
| `preventDuplicate`, `dedupeKey`, `dedupeScope` | Drop duplicates, by content or by your own key. |
|
|
400
|
+
| `pauseOnHover`, `pauseOnFocus`, `swipeDismiss`, `swipeDirection`, `dragDismiss` | Behaviour; see the [settings](#configure-it). |
|
|
401
|
+
| `role`, `ariaLive` | Override the announcement (see [Accessibility](#accessibility)). |
|
|
402
|
+
| `group` | The id of a group the toast belongs to. |
|
|
403
|
+
| `animation` | Animation settings (a CSS animation by default; spring and other types are available). |
|
|
404
|
+
| `onShow`, `onHide`, `onUpdate` | Lifecycle callbacks. |
|
|
405
|
+
|
|
406
|
+
## Accessibility
|
|
407
|
+
|
|
408
|
+
Toasts live in a region that is announced politely. An **error** toast is a `role="alert"` with `aria-live="assertive"`,
|
|
409
|
+
so a screen reader interrupts to read it; every other level is `role="status"` with `aria-live="polite"`. The close button
|
|
410
|
+
is labelled "Close notification", and the icons are decorative (a different shape for each level, so a toast is not told
|
|
411
|
+
apart by colour alone). Override the announcement of one toast with `role` and `ariaLive`.
|
|
412
|
+
|
|
413
|
+
**Keyboard.** Every toast is a Tab stop, so its buttons can be reached before it goes away. **Alt+T** (`hotkey`) moves
|
|
414
|
+
focus to the newest toast and opens the stack; **Escape** dismisses the focused toast and moves on to the next one, or back
|
|
415
|
+
to where you were. While a toast has keyboard focus, or the pointer is over the stack, the timers wait. With
|
|
416
|
+
`prefers-reduced-motion` the toasts fade instead of sliding.
|
|
417
|
+
|
|
418
|
+
## API
|
|
419
|
+
|
|
420
|
+
`toast`:
|
|
421
|
+
|
|
422
|
+
| Method | |
|
|
423
|
+
| --- | --- |
|
|
424
|
+
| `toast(message, options?)` | A plain toast, with no level and no icon. |
|
|
425
|
+
| `info`, `success`, `warning`, `error`, `loading` `(message, options?)` | A toast of that level. |
|
|
426
|
+
| `show(options)` | Show a toast from full options; returns `{ id, options, dismiss(), update(options) }`. |
|
|
427
|
+
| `promise(promise, { loading, success, error })` | A toast that follows a promise (also `onSuccess` and `onError`); resolves with the promise's value. |
|
|
428
|
+
| `update(id, options)` | Change a toast. |
|
|
429
|
+
| `dismiss(id?)` / `clear()` | Remove one toast, or (with no id) every toast. |
|
|
430
|
+
| `configure(settings)` | Set the [settings](#configure-it). |
|
|
431
|
+
|
|
432
|
+
`toastAdvanced` (`toastPro`) has all of those and more:
|
|
433
|
+
|
|
434
|
+
| Method | |
|
|
435
|
+
| --- | --- |
|
|
436
|
+
| `group(id, options)` | Show a toast that belongs to a group. |
|
|
437
|
+
| `getConfig()` | Read the settings. |
|
|
438
|
+
| `getToasts()` / `getGroups()` / `getState()` | The toasts, the groups, or both with the queue and the settings. |
|
|
439
|
+
| `subscribe(listener)` | Call `listener(state)` when the toasts change; returns an unsubscribe function. |
|
|
440
|
+
| `use(plugin)` | Install a plugin: `{ name, install(manager), uninstall? }`. |
|
|
441
|
+
| `onEditorEvent(event, callback)` / `triggerEditorEvent(event, toast, ...args)` | Connect toasts to your editor's events. |
|
|
442
|
+
| `destroy()` | Remove every toast and the toast region. |
|
|
443
|
+
|
|
444
|
+
The classes and types are exported too: `ToastManager`, and `ToastOptions`, `ToastConfig`, `ToastInstance`,
|
|
445
|
+
`ToastPosition`, `ToastTheme`, `ToastPromiseOptions` and more. If you are upgrading from 1.x, see the
|
|
446
|
+
[migration guide](https://github.com/ajaykr089/Editora/blob/main/packages/editora-toast/MIGRATION_GUIDE.md).
|
|
447
|
+
|
|
448
|
+
## Upgrading from 2.0
|
|
449
|
+
|
|
450
|
+
2.1 changes how toasts look and where they sit; nothing was removed.
|
|
451
|
+
|
|
452
|
+
- **The look.** The card is opaque and neutral, with a status icon, instead of a see-through tint with a coloured stripe
|
|
453
|
+
(the page showed through the text). The `dark` theme is dark (it was a white card), and the primary button is readable in
|
|
454
|
+
dark mode. `richColors` gives the tinted card back. `configure({ icons: false })` removes the icons.
|
|
455
|
+
- **Stacking.** Several toasts fold into a deck by default, and the newest toast is nearest the edge of the screen (it
|
|
456
|
+
used to be farthest). To get a plain list: `configure({ stack: false })`.
|
|
457
|
+
- **Timers.** Hovering or focusing the stack holds every toast and keeps the time that was left; before, each toast was
|
|
458
|
+
held on its own and started again from the full duration.
|
|
459
|
+
- **Keyboard.** Toasts are Tab stops, Alt+T and Escape work, and `pauseOnFocus` is on. `configure({ hotkey: false })` turns the shortcut off.
|
|
460
|
+
- **The simple API** gained `toast(message)`, `promise`, `update`, `dismiss`, `clear`, `configure` and `show`.
|
|
461
|
+
- **Browsers.** The layout uses the individual `translate` and `scale` properties: Chrome 104, Safari 14.1, Firefox 72 or later.
|
|
462
|
+
- If you styled toasts with CSS, the accent stripe (`::before`) and the tinted `background` of the level classes are gone: set
|
|
463
|
+
`--et-*` variables or `--et-accent`, or restyle `.editora-toast`.
|
|
464
|
+
|
|
465
|
+
## Part of Editora
|
|
466
|
+
|
|
467
|
+
[`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) depends on this package.
|
|
468
|
+
|
|
469
|
+
## License
|
|
939
470
|
|
|
940
|
-
|
|
941
|
-
// New configuration options in v2.0.0
|
|
942
|
-
toast.configure({
|
|
943
|
-
theme: 'system', // New themes: glass, neon, retro, ocean, etc.
|
|
944
|
-
swipeDismiss: true, // Mobile gesture support
|
|
945
|
-
dragDismiss: false,
|
|
946
|
-
animation: {
|
|
947
|
-
type: 'spring', // New spring physics animations
|
|
948
|
-
config: { stiffness: 120, damping: 12 }
|
|
949
|
-
},
|
|
950
|
-
queueStrategy: 'priority', // Priority-based queuing
|
|
951
|
-
enableKeyboardNavigation: true // Enhanced accessibility
|
|
952
|
-
});
|
|
953
|
-
```
|
|
954
|
-
|
|
955
|
-
For more detailed migration information, see the [migration guide](./MIGRATION_GUIDE.md).
|
|
471
|
+
MIT ยฉ [Ajay Kumar](https://github.com/ajaykr089)
|