@editora/toast 2.0.9 โ 2.0.10
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 +10 -0
- package/README.md +274 -878
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# Change Log
|
|
2
2
|
|
|
3
|
+
## 2.0.10
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 16ae8ee: Rewrite the READMEs of `@editora/light-code-editor`, `@editora/themes`, `@editora/ui-core`, `@editora/ui-react`, `@editora/ui-sortable` and `@editora/toast`, which are the npm pages of these packages, with screenshots and examples.
|
|
8
|
+
|
|
9
|
+
Their images and links were relative paths that npm cannot show, and several examples did not run. Every example is now a file that is type-checked in strict mode and run in Chromium (React ones under `StrictMode`, drag and drop with the pointer and the keyboard), and the README quotes it word for word (`npm run check:readme-examples`). The screenshots are taken from the same examples (`npm run readme:screenshots`).
|
|
10
|
+
|
|
11
|
+
Things the READMEs now get right that they did not: the `@editora/themes` tokens only set text, border and shadow colours (backgrounds are set by rules), the helpers it exports are documented; `@editora/ui-core` and `@editora/ui-react` list measured bundle sizes (a Button imported from the `@editora/ui-react` root is 1 MB gzipped up front, from its own entry 54 KB up front plus the rest of `ui-core` loaded later); `@editora/toast` documents its defaults (bottom right, four seconds, three visible, theme `system`) and that it is safe to import on the server.
|
|
12
|
+
|
|
3
13
|
## 2.0.9
|
|
4
14
|
|
|
5
15
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,955 +1,351 @@
|
|
|
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
|
-
### Advanced Features
|
|
41
|
-

|
|
42
|
-
|
|
43
|
-
### Async Operations
|
|
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. Promise toasts, actions, progress, thirteen themes, seven positions and screen-reader announcements.
|
|
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="Ten toasts stacked in the top-right corner, one in each of the light, 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
|
+
- **Promise toasts.** One toast follows a promise from *loading* to *success* or *error*.
|
|
30
|
+
- **Actions and progress**: buttons in the toast, and a progress bar with an optional percentage.
|
|
31
|
+
- **Thirteen themes and seven positions**, a queue (three toasts show at once by default), duplicate prevention and
|
|
32
|
+
swipe-to-dismiss.
|
|
33
|
+
- **Accessible.** Errors are announced as alerts, the rest politely, and a close button is labelled.
|
|
34
|
+
- **Small.** 9 KB gzipped, plus 6 KB of CSS. No dependencies.
|
|
35
|
+
- **Safe on the server.** The package imports in Node and the calls do nothing there, so a call in shared code does not
|
|
36
|
+
break server rendering.
|
|
37
|
+
- Written in TypeScript. A script tag works too (a UMD build).
|
|
38
|
+
|
|
39
|
+
## Install
|
|
94
40
|
|
|
95
41
|
```bash
|
|
96
42
|
npm install @editora/toast
|
|
97
43
|
```
|
|
98
44
|
|
|
99
|
-
##
|
|
45
|
+
## Quick start
|
|
100
46
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
### Basic CDN Setup
|
|
47
|
+
```ts
|
|
48
|
+
import { toast } from '@editora/toast';
|
|
49
|
+
import '@editora/toast/toast.css';
|
|
105
50
|
|
|
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>
|
|
51
|
+
toast.success('Document saved');
|
|
52
|
+
toast.info('A new version is available');
|
|
53
|
+
toast.warning('Storage is almost full');
|
|
54
|
+
toast.error('Upload failed');
|
|
154
55
|
```
|
|
155
56
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
- **CSS**: `https://cdn.jsdelivr.net/npm/@editora/toast@latest/dist/toast.css`
|
|
160
|
-
|
|
161
|
-
> **Note**: Replace `@latest` with a specific version number (e.g., `@2.0.0`) for production use to avoid unexpected updates.
|
|
162
|
-
|
|
163
|
-
## ๐ Quick Start
|
|
57
|
+
<p align="center">
|
|
58
|
+
<img src="https://raw.githubusercontent.com/ajaykr089/Editora/main/packages/editora-toast/docs/images/levels.png" alt="Three toasts in the bottom-right corner: Document saved in green, A new version is available in blue and Storage is almost full in orange" width="440">
|
|
59
|
+
</p>
|
|
164
60
|
|
|
165
|
-
|
|
61
|
+
Toasts appear in the bottom-right corner and go away after four seconds. Three are visible at once; the rest wait in a
|
|
62
|
+
queue (a fourth toast, *Upload failed* above, appears when there is room).
|
|
166
63
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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
|
-
```
|
|
64
|
+
`toast` is the simple API: `toast.info`, `toast.success`, `toast.warning`, `toast.error` and `toast.loading`, each taking
|
|
65
|
+
a message and, if you like, an options object or a duration in milliseconds. For everything else there is
|
|
66
|
+
`toastAdvanced` (also exported as `toastPro`).
|
|
177
67
|
|
|
178
|
-
|
|
68
|
+
## Titles, actions and progress
|
|
179
69
|
|
|
180
|
-
```
|
|
70
|
+
```ts
|
|
181
71
|
import { toastAdvanced as toast } from '@editora/toast';
|
|
182
|
-
import
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
72
|
+
import '@editora/toast/toast.css';
|
|
73
|
+
|
|
74
|
+
// A toast with a title, a description, actions and progress. duration: 0 keeps it until it is dismissed.
|
|
75
|
+
const report = toast.show({
|
|
186
76
|
level: 'success',
|
|
187
|
-
|
|
77
|
+
title: 'Report ready',
|
|
78
|
+
description: 'Q3-summary.pdf is 2.4 MB',
|
|
188
79
|
actions: [
|
|
189
|
-
{ label: '
|
|
190
|
-
{ label: '
|
|
191
|
-
{ label: 'Dismiss', onClick: () => notification.dismiss() }
|
|
80
|
+
{ label: 'Open', primary: true, onClick: () => console.log('open') },
|
|
81
|
+
{ label: 'Dismiss', onClick: () => report.dismiss() }
|
|
192
82
|
],
|
|
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'
|
|
222
|
-
});
|
|
223
|
-
|
|
224
|
-
toast.group('file-operations', {
|
|
225
|
-
message: 'File 2 processed',
|
|
226
|
-
level: 'success'
|
|
83
|
+
duration: 0
|
|
227
84
|
});
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
## ๐๏ธ Configuration
|
|
231
85
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
|
86
|
+
const upload = toast.show({
|
|
87
|
+
level: 'info',
|
|
88
|
+
message: 'Uploading photos',
|
|
89
|
+
progress: { value: 64, showPercentage: true },
|
|
90
|
+
duration: 0
|
|
281
91
|
});
|
|
282
92
|
```
|
|
283
93
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
94
|
+
<p align="center">
|
|
95
|
+
<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" width="440">
|
|
96
|
+
</p>
|
|
287
97
|
|
|
288
|
-
|
|
98
|
+
`show()` returns the toast: `dismiss()` removes it and `update(options)` changes it. Pressing an action runs its `onClick`
|
|
99
|
+
and closes the toast; give the action `dismissOnClick: false` to keep the toast open.
|
|
289
100
|
|
|
290
|
-
|
|
101
|
+
## Promises and updates
|
|
291
102
|
|
|
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
|
|
103
|
+
`toast.promise()` shows one toast that becomes the result of a promise, and `update()` changes any toast by id:
|
|
305
104
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
```typescript
|
|
105
|
+
```ts
|
|
309
106
|
import { toastAdvanced as toast } from '@editora/toast';
|
|
310
|
-
import
|
|
311
|
-
// Set global theme
|
|
312
|
-
toast.configure({
|
|
313
|
-
theme: 'glass' // or 'neon', 'retro', 'ocean', etc.
|
|
314
|
-
});
|
|
107
|
+
import '@editora/toast/toast.css';
|
|
315
108
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
message: 'Hello World',
|
|
319
|
-
theme: 'colored'
|
|
109
|
+
const saveDocument = new Promise<{ name: string }>((resolve) => {
|
|
110
|
+
setTimeout(() => resolve({ name: 'Q3-summary.pdf' }), 1500);
|
|
320
111
|
});
|
|
321
|
-
```
|
|
322
|
-
|
|
323
|
-
### CSS Variables
|
|
324
|
-
|
|
325
|
-
```css
|
|
326
|
-
:root {
|
|
327
|
-
--editora-toast-bg: rgba(0, 0, 0, 0.85);
|
|
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
|
-
}
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
### Theme Classes
|
|
338
|
-
|
|
339
|
-
```html
|
|
340
|
-
<!-- Apply theme globally -->
|
|
341
|
-
<div data-theme="glass">
|
|
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
|
-
```
|
|
349
|
-
|
|
350
|
-
## ๐ฏ Advanced Features
|
|
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
112
|
|
|
360
|
-
//
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
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
|
-
}
|
|
113
|
+
// One toast that moves from loading to success or error by itself.
|
|
114
|
+
toast.promise(saveDocument, {
|
|
115
|
+
loading: 'Saving document...',
|
|
116
|
+
success: (file) => `Saved ${file.name}`,
|
|
117
|
+
error: (error) => `Could not save: ${error.message}`
|
|
384
118
|
});
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
### Interactive Actions
|
|
388
|
-

|
|
389
119
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
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
|
-
});
|
|
120
|
+
// Or update a toast yourself.
|
|
121
|
+
const sync = toast.loading('Syncing...');
|
|
122
|
+
setTimeout(() => {
|
|
123
|
+
toast.update(sync.id, { message: 'Everything is up to date', level: 'success' });
|
|
124
|
+
}, 2500);
|
|
418
125
|
```
|
|
419
126
|
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
message: 'Processing files...',
|
|
431
|
-
level: 'info',
|
|
432
|
-
progress: {
|
|
433
|
-
value: 0,
|
|
434
|
-
showPercentage: true,
|
|
435
|
-
color: '#007acc'
|
|
436
|
-
}
|
|
437
|
-
});
|
|
127
|
+
<table>
|
|
128
|
+
<tr>
|
|
129
|
+
<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"></td>
|
|
130
|
+
<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"></td>
|
|
131
|
+
</tr>
|
|
132
|
+
<tr>
|
|
133
|
+
<td align="center"><sub>While it works</sub></td>
|
|
134
|
+
<td align="center"><sub>After the promise resolves and the update</sub></td>
|
|
135
|
+
</tr>
|
|
136
|
+
</table>
|
|
438
137
|
|
|
439
|
-
|
|
440
|
-
|
|
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
|
-
```
|
|
138
|
+
`toast.promise()` returns the promise you gave it, so you can still `await` it. If you only need the message, `success`
|
|
139
|
+
and `error` can be plain strings.
|
|
458
140
|
|
|
459
|
-
|
|
460
|
-

|
|
141
|
+
## In React, and in any framework
|
|
461
142
|
|
|
462
|
-
|
|
143
|
+
There is nothing to render. Call `toast` from a handler, an effect or a service:
|
|
463
144
|
|
|
464
|
-
```
|
|
145
|
+
```tsx
|
|
465
146
|
import { toastAdvanced as toast } from '@editora/toast';
|
|
466
|
-
import
|
|
467
|
-
// Create a loading toast
|
|
468
|
-
const loadingToast = toast.loading('Connecting to server...');
|
|
147
|
+
import '@editora/toast/toast.css';
|
|
469
148
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
progress: { value: 25, showPercentage: true }
|
|
475
|
-
});
|
|
476
|
-
}, 1000);
|
|
477
|
-
|
|
478
|
-
// Update with success
|
|
479
|
-
setTimeout(() => {
|
|
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);
|
|
488
|
-
```
|
|
489
|
-
|
|
490
|
-
### Toast Grouping
|
|
491
|
-

|
|
492
|
-
|
|
493
|
-
Group related notifications together:
|
|
494
|
-
|
|
495
|
-
```typescript
|
|
496
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
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
|
-
});
|
|
511
|
-
|
|
512
|
-
// Group error notifications
|
|
513
|
-
toast.group('validation-errors', {
|
|
514
|
-
message: 'Invalid email format',
|
|
515
|
-
level: 'error',
|
|
516
|
-
icon: 'โ ๏ธ'
|
|
517
|
-
});
|
|
149
|
+
async function saveDraft() {
|
|
150
|
+
await new Promise((resolve) => setTimeout(resolve, 800));
|
|
151
|
+
return { name: 'draft.md' };
|
|
152
|
+
}
|
|
518
153
|
|
|
519
|
-
toast.
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
154
|
+
// There is nothing to mount: call toast from any handler or effect.
|
|
155
|
+
export default function SaveButton() {
|
|
156
|
+
return (
|
|
157
|
+
<button
|
|
158
|
+
onClick={() =>
|
|
159
|
+
toast.promise(saveDraft(), {
|
|
160
|
+
loading: 'Saving...',
|
|
161
|
+
success: (file) => `Saved ${file.name}`,
|
|
162
|
+
error: 'Could not save'
|
|
163
|
+
})
|
|
164
|
+
}
|
|
165
|
+
>
|
|
166
|
+
Save
|
|
167
|
+
</button>
|
|
168
|
+
);
|
|
169
|
+
}
|
|
524
170
|
```
|
|
525
171
|
|
|
526
|
-
|
|
527
|
-

|
|
172
|
+
## From a script tag
|
|
528
173
|
|
|
529
|
-
|
|
174
|
+
The UMD build defines three globals: `toast`, `toastAdvanced` and `toastPro` (the same object as `toastAdvanced`).
|
|
175
|
+
Pin a version in production, as here:
|
|
530
176
|
|
|
531
|
-
```
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
toast.show({
|
|
535
|
-
message: 'How was your experience?',
|
|
536
|
-
level: 'info',
|
|
537
|
-
icon: 'โญ',
|
|
538
|
-
render: () => {
|
|
539
|
-
const container = document.createElement('div');
|
|
540
|
-
container.innerHTML = `
|
|
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!');
|
|
555
|
-
}
|
|
556
|
-
});
|
|
177
|
+
```html
|
|
178
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@editora/toast@2/dist/toast.css" />
|
|
179
|
+
<script src="https://cdn.jsdelivr.net/npm/@editora/toast@2/dist/index.umd.js"></script>
|
|
557
180
|
|
|
558
|
-
|
|
559
|
-
},
|
|
560
|
-
duration: 10000
|
|
561
|
-
});
|
|
562
|
-
```
|
|
181
|
+
<button id="save">Save</button>
|
|
563
182
|
|
|
564
|
-
|
|
183
|
+
<script>
|
|
184
|
+
document.getElementById('save').onclick = () => {
|
|
185
|
+
// The script defines three globals: toast, toastAdvanced and toastPro (the same object as toastAdvanced).
|
|
186
|
+
toast.success('Saved from a CDN');
|
|
565
187
|
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
console.log('Toast about to show:', toast.message);
|
|
188
|
+
const notification = toastAdvanced.show({
|
|
189
|
+
message: 'File uploaded',
|
|
190
|
+
level: 'success',
|
|
191
|
+
actions: [
|
|
192
|
+
{ label: 'View', onClick: () => console.log('view') },
|
|
193
|
+
{ label: 'Dismiss', onClick: () => notification.dismiss() }
|
|
194
|
+
],
|
|
195
|
+
duration: 0
|
|
575
196
|
});
|
|
576
|
-
}
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
toast.use(myPlugin);
|
|
580
|
-
```
|
|
581
|
-
|
|
582
|
-
## ๐ฑ Positions
|
|
583
|
-
|
|
584
|
-
```typescript
|
|
585
|
-
toast.show({
|
|
586
|
-
message: 'Hello World',
|
|
587
|
-
position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center'
|
|
588
|
-
});
|
|
197
|
+
};
|
|
198
|
+
</script>
|
|
589
199
|
```
|
|
590
200
|
|
|
591
|
-
##
|
|
201
|
+
## Configure it
|
|
592
202
|
|
|
593
|
-
|
|
203
|
+
`configure()` sets the defaults for every toast from then on. A single toast can still override them:
|
|
594
204
|
|
|
595
|
-
```
|
|
205
|
+
```ts
|
|
596
206
|
import { toastAdvanced as toast } from '@editora/toast';
|
|
597
|
-
import
|
|
598
|
-
// Spring animation with custom physics
|
|
599
|
-
toast.show({
|
|
600
|
-
message: 'Spring animated toast!',
|
|
601
|
-
level: 'success',
|
|
602
|
-
animation: {
|
|
603
|
-
type: 'spring',
|
|
604
|
-
config: {
|
|
605
|
-
stiffness: 120, // Spring stiffness (default: 100)
|
|
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
|
-
});
|
|
612
|
-
```
|
|
613
|
-
|
|
614
|
-
### Custom Animation Hooks
|
|
615
|
-
|
|
616
|
-
```typescript
|
|
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
|
-
```
|
|
657
|
-
|
|
658
|
-
### Global Animation Configuration
|
|
207
|
+
import '@editora/toast/toast.css';
|
|
659
208
|
|
|
660
|
-
|
|
661
|
-
import { toastAdvanced as toast } from '@editora/toast';
|
|
662
|
-
import "@editora/toast/toast.css";
|
|
663
|
-
// Set default animation for all toasts
|
|
209
|
+
// Settings for every toast from now on. A toast can still override them.
|
|
664
210
|
toast.configure({
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
211
|
+
position: 'top-center',
|
|
212
|
+
duration: 6000,
|
|
213
|
+
maxVisible: 3,
|
|
214
|
+
theme: 'ocean',
|
|
215
|
+
closeButton: true,
|
|
216
|
+
preventDuplicate: true
|
|
669
217
|
});
|
|
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
218
|
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
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
|
-
}
|
|
716
|
-
});
|
|
219
|
+
toast.info('Welcome back');
|
|
220
|
+
toast.info('Welcome back'); // the duplicate is dropped
|
|
221
|
+
toast.warning('Your plan renews tomorrow', { theme: 'sunset', duration: 0 });
|
|
717
222
|
```
|
|
718
223
|
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
224
|
+
| Setting | Default | |
|
|
225
|
+
| --- | --- | --- |
|
|
226
|
+
| `position` | `'bottom-right'` | Where toasts appear (see [Positions](#positions)). |
|
|
227
|
+
| `duration` | `4000` | How long a toast stays, in milliseconds. `0` keeps it until it is dismissed. |
|
|
228
|
+
| `maxVisible` | `3` | How many show at once; the others wait in the queue. (`visibleToasts` is an alias.) |
|
|
229
|
+
| `queueStrategy` | `'fifo'` | `'fifo'` or `'lifo'`: which waiting toast comes next. |
|
|
230
|
+
| `theme` | `'system'` | One of the [themes](#themes). |
|
|
231
|
+
| `closeButton` | `false` | Show a close button on every toast. |
|
|
232
|
+
| `preventDuplicate` | `false` | Drop a toast whose content is already showing. With `dedupeScope`: `'visible'`, `'queue'` or `'all'` (the default). |
|
|
233
|
+
| `pauseOnHover`, `pauseOnFocus`, `pauseOnWindowBlur` | `true`, `false`, `false` | Pause the timer while the pointer is over a toast, a toast has focus, or the window is in the background. |
|
|
234
|
+
| `swipeDismiss`, `swipeDirection`, `dragDismiss` | `true`, `'any'`, `false` | Dismiss by swiping, in which direction, and by dragging. |
|
|
235
|
+
| `stack`, `expand`, `gap` | `false`, `true`, `8` | How several visible toasts are laid out, and the gap between them. |
|
|
236
|
+
| `offset`, `mobileOffset`, `zIndex` | `16`, `16`, none | The distance from the edge of the screen, on desktop and on mobile, and the stacking order. |
|
|
237
|
+
| `rtl` | `false` | Right-to-left layout. |
|
|
238
|
+
| `richColors` | `false` | Richer colours for the levels. |
|
|
239
|
+
| `container` | the page body | The element toasts are added to. |
|
|
240
|
+
|
|
241
|
+
`toast.getConfig()` returns the current settings.
|
|
242
|
+
|
|
243
|
+
## Themes
|
|
244
|
+
|
|
245
|
+
`light`, `dark`, `system`, `colored`, `minimal`, `glass`, `neon`, `retro`, `ocean`, `forest`, `sunset`, `midnight` and
|
|
246
|
+
`custom`. Set one for all toasts with `configure({ theme })`, or for one toast with `{ theme }`:
|
|
247
|
+
|
|
248
|
+
```ts
|
|
722
249
|
import { toastAdvanced as toast } from '@editora/toast';
|
|
723
|
-
import
|
|
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 });
|
|
731
|
-
```
|
|
732
|
-
|
|
733
|
-
## ๐ API Reference
|
|
734
|
-
|
|
735
|
-
### Core Methods
|
|
736
|
-
|
|
737
|
-
- `toast.show(options)` - Show a toast with full options
|
|
738
|
-
- `toast.update(id, options)` - Update an existing toast dynamically
|
|
739
|
-
- `toast.dismiss(id?)` - Dismiss a specific toast or all toasts
|
|
740
|
-
- `toast.clear()` - Clear all visible toasts
|
|
741
|
-
|
|
742
|
-
### Convenience Methods
|
|
743
|
-
|
|
744
|
-
- `toast.info(message, options?)` - Info level toast
|
|
745
|
-
- `toast.success(message, options?)` - Success level toast
|
|
746
|
-
- `toast.error(message, options?)` - Error level toast
|
|
747
|
-
- `toast.warning(message, options?)` - Warning level toast
|
|
748
|
-
- `toast.loading(message, options?)` - Loading state toast
|
|
749
|
-
|
|
750
|
-
### Advanced Methods (v2.0.0)
|
|
751
|
-
|
|
752
|
-
- `toast.promise(promise, options)` - Promise lifecycle toasts with automatic state transitions
|
|
753
|
-
- `toast.group(id, options)` - Group related toasts with stacking behavior
|
|
754
|
-
- `toast.configure(config)` - Update global configuration
|
|
755
|
-
- `toast.use(plugin)` - Install a plugin
|
|
756
|
-
- `toast.getState()` - Read visible, queued, grouped, and configured toast state
|
|
757
|
-
- `toast.subscribe(listener)` - Subscribe to state changes for headless/custom renderers
|
|
758
|
-
- `toast.onEditorEvent(event, handler)` - Listen for editor integration events
|
|
759
|
-
- `toast.triggerEditorEvent(event, data)` - Trigger editor integration events
|
|
760
|
-
|
|
761
|
-
### Toast Options Interface
|
|
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
|
-
}
|
|
250
|
+
import '@editora/toast/toast.css';
|
|
810
251
|
|
|
811
|
-
|
|
812
|
-
label: string;
|
|
813
|
-
onClick: () => void;
|
|
814
|
-
primary?: boolean;
|
|
815
|
-
dismissOnClick?: boolean;
|
|
816
|
-
altText?: string;
|
|
817
|
-
}
|
|
252
|
+
toast.configure({ position: 'top-right', maxVisible: 10, gap: 8 });
|
|
818
253
|
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
}
|
|
254
|
+
const themes = [
|
|
255
|
+
'light', 'colored', 'minimal', 'glass', 'neon', 'retro', 'ocean', 'forest', 'sunset', 'midnight'
|
|
256
|
+
] as const;
|
|
823
257
|
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
config?: SpringConfig;
|
|
827
|
-
show?: AnimationFunction;
|
|
828
|
-
hide?: AnimationFunction;
|
|
829
|
-
update?: AnimationFunction;
|
|
258
|
+
for (const theme of themes) {
|
|
259
|
+
toast.info(`The ${theme} theme`, { theme, duration: 0 });
|
|
830
260
|
}
|
|
831
261
|
```
|
|
832
262
|
|
|
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
|
|
263
|
+
The picture at the top of this page is that code. `system` (the default) follows the operating system's light or
|
|
264
|
+
dark setting. Each toast carries `data-theme` and level classes (`editora-toast-info`, ...), so you can restyle the
|
|
265
|
+
themes with CSS.
|
|
861
266
|
|
|
862
|
-
##
|
|
863
|
-
|
|
864
|
-
```bash
|
|
865
|
-
# Install dependencies
|
|
866
|
-
npm install
|
|
867
|
-
|
|
868
|
-
# Build
|
|
869
|
-
npm run build
|
|
870
|
-
|
|
871
|
-
# Development watch
|
|
872
|
-
npm run dev
|
|
873
|
-
|
|
874
|
-
# Clean
|
|
875
|
-
npm run clean
|
|
876
|
-
```
|
|
267
|
+
## Positions
|
|
877
268
|
|
|
878
|
-
|
|
269
|
+
`top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right` and `center`:
|
|
879
270
|
|
|
880
|
-
|
|
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
|
|
894
|
-
|
|
895
|
-
### From v1.x to v2.0.0
|
|
896
|
-
|
|
897
|
-
The v2.0.0 release introduces powerful new features while maintaining **full backward compatibility**. Your existing code will continue to work without changes.
|
|
898
|
-
|
|
899
|
-
#### โจ New Features in v2.0.0
|
|
900
|
-
|
|
901
|
-
```typescript
|
|
902
|
-
// v1.x (still works)
|
|
903
|
-
import { toast } from '@editora/toast';
|
|
904
|
-
import "@editora/toast/toast.css";
|
|
905
|
-
toast.success('Hello World', { theme: 'light', position: 'top-right' });
|
|
906
|
-
|
|
907
|
-
// v2.0.0 advanced features
|
|
271
|
+
```ts
|
|
908
272
|
import { toastAdvanced as toast } from '@editora/toast';
|
|
909
|
-
import
|
|
910
|
-
// Promise lifecycle toasts
|
|
911
|
-
toast.promise(fetchData(), {
|
|
912
|
-
loading: 'Loading...',
|
|
913
|
-
success: 'Data loaded!',
|
|
914
|
-
error: 'Failed to load'
|
|
915
|
-
});
|
|
273
|
+
import '@editora/toast/toast.css';
|
|
916
274
|
|
|
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
|
-
});
|
|
275
|
+
toast.configure({ maxVisible: 10 });
|
|
928
276
|
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
277
|
+
const positions = [
|
|
278
|
+
'top-left', 'top-center', 'top-right',
|
|
279
|
+
'bottom-left', 'bottom-center', 'bottom-right',
|
|
280
|
+
'center'
|
|
281
|
+
] as const;
|
|
932
282
|
|
|
933
|
-
|
|
934
|
-
toast.
|
|
935
|
-
|
|
283
|
+
for (const position of positions) {
|
|
284
|
+
toast.success(position, { position, duration: 0 });
|
|
285
|
+
}
|
|
936
286
|
```
|
|
937
287
|
|
|
938
|
-
|
|
288
|
+
<p align="center">
|
|
289
|
+
<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">
|
|
290
|
+
</p>
|
|
291
|
+
|
|
292
|
+
## Toast options
|
|
293
|
+
|
|
294
|
+
Everything `show()` accepts. All of it is optional except a message (or a title):
|
|
295
|
+
|
|
296
|
+
| Option | |
|
|
297
|
+
| --- | --- |
|
|
298
|
+
| `message`, `title`, `description` | The text. |
|
|
299
|
+
| `level` | `'info'`, `'success'`, `'warning'`, `'error'` or `'loading'`. |
|
|
300
|
+
| `icon` | An icon, as a string. |
|
|
301
|
+
| `actions`, `action`, `cancel` | Buttons: `{ label, onClick, primary?, dismissOnClick? }`. |
|
|
302
|
+
| `progress` | `{ value, showPercentage? }`, with `value` from 0 to 100. |
|
|
303
|
+
| `duration`, `persistent` | How long it stays (`0`, or `persistent: true`, keeps it until dismissed). |
|
|
304
|
+
| `position`, `theme`, `customClass`, `rtl` | Where it appears and how it looks. |
|
|
305
|
+
| `closable` / `closeButton` | Show a close button. |
|
|
306
|
+
| `html` | Render `message` as HTML. Only inline formatting, lists and safe links are kept. |
|
|
307
|
+
| `render` | Build the toast yourself: `(toast) => HTMLElement`. |
|
|
308
|
+
| `priority`, `important` | Show higher priorities first; `important` also pushes lower-priority toasts out. |
|
|
309
|
+
| `preventDuplicate`, `dedupeKey`, `dedupeScope` | Drop duplicates, by content or by your own key. |
|
|
310
|
+
| `pauseOnHover`, `pauseOnFocus`, `swipeDismiss`, `swipeDirection`, `dragDismiss` | Behaviour; see the [settings](#configure-it). |
|
|
311
|
+
| `role`, `ariaLive` | Override the announcement (see [Accessibility](#accessibility)). |
|
|
312
|
+
| `group` | The id of a group the toast belongs to. |
|
|
313
|
+
| `animation` | Animation settings (a CSS animation by default; spring and other types are available). |
|
|
314
|
+
| `onShow`, `onHide`, `onUpdate` | Lifecycle callbacks. |
|
|
315
|
+
|
|
316
|
+
## Accessibility
|
|
317
|
+
|
|
318
|
+
Toasts live in a region that is announced politely. An **error** toast is a `role="alert"` with `aria-live="assertive"`,
|
|
319
|
+
so a screen reader interrupts to read it; every other level is `role="status"` with `aria-live="polite"`. The close button
|
|
320
|
+
is labelled "Close notification". Override the announcement of one toast with `role` and `ariaLive`. Actions are buttons,
|
|
321
|
+
so a keyboard can reach them, and `pauseOnFocus` pauses the timer while a toast has focus.
|
|
322
|
+
|
|
323
|
+
## API
|
|
324
|
+
|
|
325
|
+
`toastAdvanced` (`toastPro`):
|
|
326
|
+
|
|
327
|
+
| Method | |
|
|
328
|
+
| --- | --- |
|
|
329
|
+
| `show(options)` | Show a toast; returns `{ id, options, dismiss(), update(options) }`. |
|
|
330
|
+
| `info`, `success`, `warning`, `error`, `loading` `(message, options?)` | Shorthands for `show`. |
|
|
331
|
+
| `update(id, options)` / `dismiss(id)` / `clear()` | Change, remove or remove every toast. |
|
|
332
|
+
| `promise(promise, { loading, success, error })` | A toast that follows a promise; also `onSuccess` and `onError` callbacks. |
|
|
333
|
+
| `group(id, options)` | Show a toast that belongs to a group. |
|
|
334
|
+
| `configure(settings)` / `getConfig()` | Set and read the [settings](#configure-it). |
|
|
335
|
+
| `getToasts()` / `getGroups()` / `getState()` | The toasts, the groups, or both with the queue and the settings. |
|
|
336
|
+
| `subscribe(listener)` | Call `listener(state)` when the toasts change; returns an unsubscribe function. |
|
|
337
|
+
| `use(plugin)` | Install a plugin: `{ name, install(manager), uninstall? }`. |
|
|
338
|
+
| `onEditorEvent(event, callback)` / `triggerEditorEvent(event, toast, ...args)` | Connect toasts to your editor's events. |
|
|
339
|
+
| `destroy()` | Remove every toast and the toast region. |
|
|
340
|
+
|
|
341
|
+
The classes and types are exported too: `ToastManager`, and `ToastOptions`, `ToastConfig`, `ToastInstance`,
|
|
342
|
+
`ToastPosition`, `ToastTheme`, `ToastPromiseOptions` and more. If you are upgrading from 1.x, see the
|
|
343
|
+
[migration guide](https://github.com/ajaykr089/Editora/blob/main/packages/editora-toast/MIGRATION_GUIDE.md).
|
|
344
|
+
|
|
345
|
+
## Part of Editora
|
|
346
|
+
|
|
347
|
+
[`@editora/ui-react`](https://www.npmjs.com/package/@editora/ui-react) depends on this package.
|
|
348
|
+
|
|
349
|
+
## License
|
|
939
350
|
|
|
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).
|
|
351
|
+
MIT ยฉ [Ajay Kumar](https://github.com/ajaykr089)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@editora/toast",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.10",
|
|
4
4
|
"description": "Enterprise toast notification library for React and web apps, with SaaS-ready UX patterns, accessibility, and high-performance lifecycle controls.",
|
|
5
5
|
"main": "dist/index.cjs.js",
|
|
6
6
|
"module": "dist/index.esm.js",
|