@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/README.md CHANGED
@@ -1,955 +1,471 @@
1
- # Editora Toast
2
-
3
- > [!IMPORTANT]
4
- > **Live Website:** https://editora-ecosystem.netlify.app/
5
- > **Storybook:** https://editora-ecosystem-storybook.netlify.app/
6
-
7
-
8
- > Advanced toast notification system with enterprise features, backward compatibility, and rich customization options.
9
-
10
- [![Version](https://img.shields.io/npm/v/@editora/toast)](https://www.npmjs.com/package/@editora/toast)
11
- [![License](https://img.shields.io/npm/l/@editora/toast)](https://github.com/ajaykr089/Editora/blob/main/LICENSE)
12
- [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
13
- [![Size](https://img.shields.io/bundlephobia/minzip/@editora/toast)](https://bundlephobia.com/package/@editora/toast)
14
-
15
- A modern, framework-agnostic toast notification library designed for enterprise applications. Features advanced UX patterns, accessibility compliance, plugin architecture, and seamless integration with rich text editors.
16
-
17
- ## ๐Ÿ“ธ Screenshots
18
-
19
- ### Animated Toast Demo
20
- ![Animated Toast Demo](toast-screenshots/toast-demo.gif)
21
-
22
- ### Hero Section
23
- ![Hero Section](toast-screenshots/hero-section.png)
24
-
25
- ### Basic Toast Types
26
- ![Basic Toast Types](toast-screenshots/basic-toast-types.png)
27
-
28
- ### Beautiful Themes
29
- ![Beautiful Themes](toast-screenshots/beautiful-themes.png)
30
-
31
- ### Interactive Actions
32
- ![Interactive Actions](toast-screenshots/interactive-actions.png)
33
-
34
- ### Interactive Feedback Form
35
- ![Interactive Feedback Form](toast-screenshots/interactive-feedback-form.png)
36
-
37
- ### Progress Scenarios
38
- ![Progress Scenarios](toast-screenshots/progress-scenarios.png)
39
-
40
- ### Advanced Features
41
- ![Advanced Features](toast-screenshots/advanced-features.png)
42
-
43
- ### Async Operations
44
- ![Async Operations](toast-screenshots/async-operations.png)
45
-
46
- ### Error Handling
47
- ![Error Handling](toast-screenshots/error-handling.png)
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
- ## ๐ŸŒ CDN Usage
50
+ ## Quick start
100
51
 
101
- You can also use Editora Toast directly from a CDN without installing it via npm. Include the following scripts in your HTML:
102
- ### Examples
103
- ``` https://editora-ecosystem.netlify.app/toast-demo.html ```
104
- ### Basic CDN Setup
52
+ ```ts
53
+ import { toast } from '@editora/toast';
54
+ import '@editora/toast/toast.css';
105
55
 
106
- ```html
107
- <!DOCTYPE html>
108
- <html lang="en">
109
- <head>
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
- ### CDN URLs
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
- - **JavaScript**: `https://cdn.jsdelivr.net/npm/@editora/toast@latest/dist/index.umd.js`
159
- - **CSS**: `https://cdn.jsdelivr.net/npm/@editora/toast@latest/dist/toast.css`
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
- > **Note**: Replace `@latest` with a specific version number (e.g., `@2.0.0`) for production use to avoid unexpected updates.
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
- ## ๐Ÿš€ Quick Start
76
+ ## Titles, actions and progress
164
77
 
165
- ### Basic Usage (Backward Compatible)
166
-
167
- ```typescript
78
+ ```ts
168
79
  import { toast } from '@editora/toast';
169
- import "@editora/toast/toast.css";
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
- ```typescript
181
- import { toastAdvanced as toast } from '@editora/toast';
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
- icon: 'โœ“',
85
+ title: 'Report ready',
86
+ description: 'Q3-summary.pdf is 2.4 MB',
188
87
  actions: [
189
- { label: 'View Document', onClick: () => console.log('View clicked') },
190
- { label: 'Share', onClick: () => console.log('Share clicked') },
191
- { label: 'Dismiss', onClick: () => notification.dismiss() }
88
+ { label: 'Open', primary: true, onClick: () => console.log('open') },
89
+ { label: 'Dismiss', onClick: () => report.dismiss() }
192
90
  ],
193
- progress: { value: 100, showPercentage: true },
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.group('file-operations', {
225
- message: 'File 2 processed',
226
- level: 'success'
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
- ## ๐ŸŽจ Theming
285
-
286
- ![Beautiful Themes](toast-screenshots/beautiful-themes.png)
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
- ### Built-in Themes
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
- Editora Toast comes with 13 beautiful themes:
110
+ ## Promises and updates
291
111
 
292
- - **`light`** - Clean white background with subtle shadows
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
- ### Usage
114
+ ```ts
115
+ import { toast } from '@editora/toast';
116
+ import '@editora/toast/toast.css';
307
117
 
308
- ```typescript
309
- import { toastAdvanced as toast } from '@editora/toast';
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
- // Per-toast theme
317
- toast.show({
318
- message: 'Hello World',
319
- theme: 'colored'
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
- ### 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
- }
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
- ### Theme Classes
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
- ```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
- ```
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
- ## ๐ŸŽฏ Advanced Features
351
-
352
- ### Promise Lifecycle Toasts
353
- ![Async Operations](toast-screenshots/async-operations.png)
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
- ### Interactive Actions
388
- ![Interactive Actions](toast-screenshots/interactive-actions.png)
153
+ ```ts
154
+ import { toast } from '@editora/toast';
155
+ import '@editora/toast/toast.css';
389
156
 
390
- Add interactive buttons to your toasts:
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
- ```typescript
393
- import { toastAdvanced as toast } from '@editora/toast';
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
- ### Progress Tracking
421
- ![Progress Scenarios](toast-screenshots/progress-scenarios.png)
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
- Built-in progress bars with customizable display:
424
-
425
- ```typescript
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
- // Update progress
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
- ### Toast Updates
460
- ![Advanced Features](toast-screenshots/advanced-features.png)
184
+ ## Icons
461
185
 
462
- Modify existing toasts dynamically:
186
+ ```ts
187
+ import { toast } from '@editora/toast';
188
+ import '@editora/toast/toast.css';
463
189
 
464
- ```typescript
465
- import { toastAdvanced as toast } from '@editora/toast';
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
- // Update with progress
471
- setTimeout(() => {
472
- toast.update(loadingToast.id, {
473
- message: 'Authenticating...',
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
- // 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);
198
+ // Or switch the built-in icons off everywhere:
199
+ // toast.configure({ icons: false });
488
200
  ```
489
201
 
490
- ### Toast Grouping
491
- ![Error Handling](toast-screenshots/error-handling.png)
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
- ```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
- });
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
- // Group error notifications
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.group('validation-errors', {
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
- ### Interactive Feedback Forms
527
- ![Interactive Feedback Form](toast-screenshots/interactive-feedback-form.png)
213
+ ```tsx
214
+ import { toast } from '@editora/toast';
215
+ import '@editora/toast/toast.css';
528
216
 
529
- Create interactive forms within toasts:
217
+ async function saveDraft() {
218
+ await new Promise((resolve) => setTimeout(resolve, 800));
219
+ return { name: 'draft.md' };
220
+ }
530
221
 
531
- ```typescript
532
- import { toastAdvanced as toast } from '@editora/toast';
533
- import "@editora/toast/toast.css";
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!');
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
- return container;
559
- },
560
- duration: 10000
561
- });
233
+ >
234
+ Save
235
+ </button>
236
+ );
237
+ }
562
238
  ```
563
239
 
564
- ## ๐Ÿ”Œ Plugins
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
- toast.use(myPlugin);
580
- ```
243
+ ## From a script tag
581
244
 
582
- ## ๐Ÿ“ฑ Positions
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
- ```typescript
585
- toast.show({
586
- message: 'Hello World',
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
- ## ๐ŸŽช Advanced Features
252
+ <button id="save">Save</button>
592
253
 
593
- ### Spring Physics Animations
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
- ```typescript
596
- import { toastAdvanced as toast } from '@editora/toast';
597
- import "@editora/toast/toast.css";
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
- });
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
- ### Custom Animation Hooks
272
+ ## Configure it
615
273
 
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
- ```
274
+ `configure()` sets the defaults for every toast from then on. A single toast can still override them:
657
275
 
658
- ### Global Animation Configuration
276
+ ```ts
277
+ import { toast } from '@editora/toast';
278
+ import '@editora/toast/toast.css';
659
279
 
660
- ```typescript
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
- animation: {
666
- type: 'spring',
667
- config: { stiffness: 150, damping: 15 }
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
- ```typescript
722
- import { toastAdvanced as toast } from '@editora/toast';
723
- import "@editora/toast/toast.css";
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
- ## ๐Ÿ“‹ 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
- }
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
- interface ToastAction {
812
- label: string;
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
- interface ToastProgress {
820
- value: number; // 0-100
821
- showPercentage?: boolean;
822
- }
328
+ const themes = [
329
+ 'light', 'dark', 'colored', 'minimal', 'glass', 'neon', 'retro', 'ocean', 'forest', 'sunset', 'midnight'
330
+ ] as const;
823
331
 
824
- interface ToastAnimation {
825
- type: 'css' | 'spring' | 'custom';
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
- ## ๐ŸŽฎ Live Demo & Examples
834
-
835
- Try out all the features with our comprehensive demo:
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
- ## ๐Ÿ”ง Build & Development
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
- ```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
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
- ## ๐ŸŒ Browser Support
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
- ### From v1.x to v2.0.0
357
+ ## Positions
896
358
 
897
- The v2.0.0 release introduces powerful new features while maintaining **full backward compatibility**. Your existing code will continue to work without changes.
359
+ `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right` and `center`:
898
360
 
899
- #### โœจ New Features in v2.0.0
900
-
901
- ```typescript
902
- // v1.x (still works)
361
+ ```ts
903
362
  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
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
- // Rich content with actions
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
- // Dynamic toast updates
930
- const toast = toast.loading('Saving...');
931
- toast.update(toast.id, { message: 'Saved!', level: 'success' });
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
- // Toast grouping
934
- toast.group('operations', { message: 'Task 1 complete', level: 'success' });
935
- toast.group('operations', { message: 'Task 2 complete', level: 'success' });
373
+ for (const position of positions) {
374
+ toast.success(position, { position, duration: 0 });
375
+ }
936
376
  ```
937
377
 
938
- #### Configuration Changes
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
- ```typescript
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)