@editora/toast 2.0.4 → 2.0.6

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 CHANGED
@@ -3,13 +3,13 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
- ## 2.0.4 (2026-03-05)
6
+ ## 2.0.5 (2026-03-08)
7
7
 
8
8
  **Note:** Version bump only for package @editora/toast
9
9
 
10
+ ## 2.0.4 (2026-03-05)
10
11
 
11
-
12
-
12
+ **Note:** Version bump only for package @editora/toast
13
13
 
14
14
  ## 2.0.0 (2026-02-14)
15
15
 
@@ -20,28 +20,31 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
20
20
  #### ✨ New Features
21
21
 
22
22
  - **Promise Lifecycle Toasts**: Automatic state transitions for async operations
23
+
23
24
  ```typescript
24
25
  toast.promise(uploadFile(), {
25
- loading: 'Uploading...',
26
- success: 'Uploaded!',
27
- error: 'Failed'
26
+ loading: "Uploading...",
27
+ success: "Uploaded!",
28
+ error: "Failed",
28
29
  });
29
30
  ```
30
31
 
31
32
  - **Rich Content Support**: HTML, icons, actions, and progress bars
33
+
32
34
  ```typescript
33
35
  toast.show({
34
- message: 'File uploaded',
35
- icon: '✓',
36
- actions: [{ label: 'View', onClick: () => {} }],
37
- progress: { value: 75 }
36
+ message: "File uploaded",
37
+ icon: "✓",
38
+ actions: [{ label: "View", onClick: () => {} }],
39
+ progress: { value: 75 },
38
40
  });
39
41
  ```
40
42
 
41
43
  - **Toast Updates**: Modify existing toasts dynamically
44
+
42
45
  ```typescript
43
- const toast = toast.loading('Saving...');
44
- toast.update(toast.id, { message: 'Saved!', level: 'success' });
46
+ const toast = toast.loading("Saving...");
47
+ toast.update(toast.id, { message: "Saved!", level: "success" });
45
48
  ```
46
49
 
47
50
  - **Multiple Positions**: Support for all screen corners and center
@@ -97,14 +100,14 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
97
100
 
98
101
  ```typescript
99
102
  toast.configure({
100
- position: 'top-right',
103
+ position: "top-right",
101
104
  duration: 5000,
102
105
  maxVisible: 5,
103
- theme: 'dark',
106
+ theme: "dark",
104
107
  pauseOnHover: true,
105
108
  enableAccessibility: true,
106
109
  swipeDismiss: true,
107
- dragDismiss: false
110
+ dragDismiss: false,
108
111
  });
109
112
  ```
110
113
 
package/README.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Editora Toast
2
2
 
3
+ > [!IMPORTANT]
4
+ > **Live Website:** https://editora-ecosystem.netlify.app/
5
+ > **Storybook:** https://editora-ecosystem-storybook.netlify.app/
6
+
7
+
3
8
  > Advanced toast notification system with enterprise features, backward compatibility, and rich customization options.
4
9
 
5
10
  [![Version](https://img.shields.io/npm/v/@editora/toast)](https://www.npmjs.com/package/@editora/toast)
@@ -11,6 +16,9 @@ A modern, framework-agnostic toast notification library designed for enterprise
11
16
 
12
17
  ## 📸 Screenshots
13
18
 
19
+ ### Animated Toast Demo
20
+ ![Animated Toast Demo](toast-screenshots/toast-demo.gif)
21
+
14
22
  ### Hero Section
15
23
  ![Hero Section](toast-screenshots/hero-section.png)
16
24
 
@@ -24,7 +32,7 @@ A modern, framework-agnostic toast notification library designed for enterprise
24
32
  ![Interactive Actions](toast-screenshots/interactive-actions.png)
25
33
 
26
34
  ### Interactive Feedback Form
27
- ![Interactive Feedback Form](toast-screenshots/nteractive-feedback-form.png)
35
+ ![Interactive Feedback Form](toast-screenshots/interactive-feedback-form.png)
28
36
 
29
37
  ### Progress Scenarios
30
38
  ![Progress Scenarios](toast-screenshots/progress-scenarios.png)
@@ -58,6 +66,8 @@ A modern, framework-agnostic toast notification library designed for enterprise
58
66
  ### Advanced Features (v2.0.0)
59
67
  - 🔄 **Toast Updates** - Modify existing toasts dynamically with smooth transitions
60
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
61
71
  - 🎪 **Custom Animation Hooks** - User-defined animation functions for complete control
62
72
  - 📍 **Multiple Positions** - Support for all screen corners and center positioning
63
73
  - 🎨 **Animation Manager** - Centralized system supporting CSS, spring, and custom animations
@@ -66,8 +76,10 @@ A modern, framework-agnostic toast notification library designed for enterprise
66
76
  - 🔄 **Promise Integration** - Seamless integration with async operations and promises
67
77
  - 📊 **Progress Tracking** - Built-in progress bars with percentage display
68
78
  - 🎯 **Action Buttons** - Interactive buttons within toasts for user actions
79
+ - ↩️ **Action/Cancel Shortcuts** - First-class `action` and `cancel` options for undo flows
69
80
  - 🎨 **Theme Variants** - Light, dark, system, colored, minimal, glass, neon, retro, ocean, forest, sunset, midnight themes
70
81
  - 🔧 **Global Configuration** - Comprehensive configuration system for all aspects
82
+ - 🧩 **Headless State** - `subscribe()` and `getState()` for custom renderers and framework adapters
71
83
 
72
84
  ### Performance & Architecture
73
85
 
@@ -88,7 +100,7 @@ npm install @editora/toast
88
100
 
89
101
  You can also use Editora Toast directly from a CDN without installing it via npm. Include the following scripts in your HTML:
90
102
  ### Examples
91
- ``` https://editora-free.netlify.app/toast-demo.html ```
103
+ ``` https://editora-ecosystem.netlify.app/toast-demo.html ```
92
104
  ### Basic CDN Setup
93
105
 
94
106
  ```html
@@ -223,28 +235,35 @@ import "@editora/toast/toast.css";
223
235
  // Global configuration with all available options
224
236
  toast.configure({
225
237
  // Positioning
226
- position: 'top-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center'
238
+ position: 'top-right', // 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center'
239
+ offset: 16,
240
+ mobileOffset: 16,
227
241
 
228
242
  // Timing
229
243
  duration: 5000, // Default duration in milliseconds
230
244
  pauseOnHover: true, // Pause timer when hovering
245
+ pauseOnWindowBlur: true, // Pause timers when the tab/window is inactive
231
246
 
232
247
  // Display
233
- maxVisible: 5, // Maximum visible toasts
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
234
254
  theme: 'system', // Theme: 'light' | 'dark' | 'system' | 'colored' | 'minimal' | 'glass' | 'neon' | 'retro' | 'ocean' | 'forest' | 'sunset' | 'midnight' | 'custom'
235
255
 
236
256
  // Accessibility
237
257
  enableAccessibility: true, // Enable screen reader support
238
- enableKeyboardNavigation: true, // Enable keyboard navigation
239
258
 
240
259
  // Interactions
241
260
  swipeDismiss: true, // Enable swipe to dismiss on mobile
242
261
  dragDismiss: false, // Enable drag to dismiss
243
- clickToDismiss: true, // Click anywhere to dismiss
244
262
 
245
263
  // Queue Management
246
- queueStrategy: 'priority', // 'fifo' | 'priority' | 'stack'
247
- maxQueueSize: 10, // Maximum queued toasts
264
+ queueStrategy: 'fifo', // 'fifo' | 'lifo'
265
+ preventDuplicate: true,
266
+ dedupeScope: 'all', // 'visible' | 'queue' | 'all'
248
267
 
249
268
  // Animations
250
269
  animation: {
@@ -258,10 +277,7 @@ toast.configure({
258
277
  },
259
278
 
260
279
  // Advanced
261
- enableHtml: false, // Allow HTML in messages (use with caution)
262
- sanitizeHtml: true, // Sanitize HTML content
263
- zIndex: 9999, // Base z-index for toasts
264
- containerClass: 'custom-container' // Custom container class
280
+ zIndex: 9999 // Base z-index for toasts
265
281
  });
266
282
  ```
267
283
 
@@ -508,7 +524,7 @@ toast.group('validation-errors', {
508
524
  ```
509
525
 
510
526
  ### Interactive Feedback Forms
511
- ![Interactive Feedback Form](toast-screenshots/nteractive-feedback-form.png)
527
+ ![Interactive Feedback Form](toast-screenshots/interactive-feedback-form.png)
512
528
 
513
529
  Create interactive forms within toasts:
514
530
 
@@ -717,6 +733,8 @@ toast.triggerEditorEvent('media-upload-progress', { progress: 50 });
717
733
  - `toast.group(id, options)` - Group related toasts with stacking behavior
718
734
  - `toast.configure(config)` - Update global configuration
719
735
  - `toast.use(plugin)` - Install a plugin
736
+ - `toast.getState()` - Read visible, queued, grouped, and configured toast state
737
+ - `toast.subscribe(listener)` - Subscribe to state changes for headless/custom renderers
720
738
  - `toast.onEditorEvent(event, handler)` - Listen for editor integration events
721
739
  - `toast.triggerEditorEvent(event, data)` - Trigger editor integration events
722
740
 
@@ -725,22 +743,27 @@ toast.triggerEditorEvent('media-upload-progress', { progress: 50 });
725
743
  ```typescript
726
744
  interface ToastOptions {
727
745
  // Content
728
- message: string;
746
+ message?: string;
747
+ title?: string;
748
+ description?: string;
729
749
  level?: 'info' | 'success' | 'error' | 'warning' | 'loading' | 'progress' | 'promise' | 'custom';
730
750
  icon?: string;
731
751
  html?: boolean;
732
- render?: () => HTMLElement;
752
+ render?: (toast: ToastInstance) => HTMLElement;
733
753
 
734
754
  // Behavior
735
755
  duration?: number;
736
756
  pauseOnHover?: boolean;
737
- clickToDismiss?: boolean;
757
+ persistent?: boolean;
758
+ closeButton?: boolean;
738
759
 
739
760
  // Positioning
740
- position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
761
+ position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center';
741
762
 
742
763
  // Interactions
743
764
  actions?: ToastAction[];
765
+ action?: ToastAction;
766
+ cancel?: ToastAction;
744
767
  swipeDismiss?: boolean;
745
768
  dragDismiss?: boolean;
746
769
 
@@ -749,30 +772,33 @@ interface ToastOptions {
749
772
 
750
773
  // Styling
751
774
  theme?: string;
752
- className?: string;
775
+ customClass?: string;
753
776
 
754
777
  // Advanced
755
- groupId?: string;
778
+ group?: string;
756
779
  priority?: number;
780
+ important?: boolean;
781
+ preventDuplicate?: boolean;
782
+ dedupeKey?: string;
783
+ dedupeScope?: 'visible' | 'queue' | 'all';
784
+ ariaLive?: 'polite' | 'assertive' | 'off';
757
785
  animation?: ToastAnimation;
758
- onShow?: (toast: Toast) => void;
759
- onHide?: (toast: Toast) => void;
760
- onUpdate?: (toast: Toast, updates: Partial<ToastOptions>) => void;
786
+ onShow?: () => void;
787
+ onHide?: () => void;
788
+ onUpdate?: (updates: Partial<ToastOptions>) => void;
761
789
  }
762
790
 
763
791
  interface ToastAction {
764
792
  label: string;
765
- onClick: (toast: Toast) => void;
766
- variant?: 'primary' | 'secondary' | 'ghost';
793
+ onClick: () => void;
767
794
  primary?: boolean;
795
+ dismissOnClick?: boolean;
796
+ altText?: string;
768
797
  }
769
798
 
770
799
  interface ToastProgress {
771
800
  value: number; // 0-100
772
801
  showPercentage?: boolean;
773
- indeterminate?: boolean;
774
- color?: string;
775
- size?: 'sm' | 'md' | 'lg';
776
802
  }
777
803
 
778
804
  interface ToastAnimation {
@@ -796,11 +822,10 @@ cd Editora/packages/editora-toast
796
822
  # Install dependencies
797
823
  npm install
798
824
 
799
- # Start the demo server
800
- npm run demo
801
- # or
802
- python3 -m http.server 8086
803
- # Then open: http://localhost:8086/examples/web/toast-demo.html
825
+ # Start the standalone CodeSandbox-ready example
826
+ cd ../../examples/editora-toast
827
+ npm install
828
+ npm run dev
804
829
  ```
805
830
 
806
831
  The demo showcases:
@@ -1,4 +1,4 @@
1
- import { ToastInstance, ToastOptions, ToastConfig, ToastManager as IToastManager, ToastPromiseOptions, ToastPlugin } from './types';
1
+ import { ToastInstance, ToastOptions, ToastConfig, ToastManager as IToastManager, ToastPromiseOptions, ToastPlugin, ToastState, ToastSubscriber } from './types';
2
2
  export declare class ToastManager implements IToastManager {
3
3
  private store;
4
4
  private queue;
@@ -7,6 +7,7 @@ export declare class ToastManager implements IToastManager {
7
7
  private config;
8
8
  private idCounter;
9
9
  private pausedToasts;
10
+ private subscribers;
10
11
  private windowFocusHandler?;
11
12
  private windowBlurHandler?;
12
13
  private visibilityChangeHandler?;
@@ -21,6 +22,8 @@ export declare class ToastManager implements IToastManager {
21
22
  configure(config: Partial<ToastConfig>): void;
22
23
  getConfig(): ToastConfig;
23
24
  getToasts(): ToastInstance[];
25
+ getState(): ToastState;
26
+ subscribe(listener: ToastSubscriber): () => void;
24
27
  getGroups(): import("./types").ToastGroup[];
25
28
  info(message: string, duration?: number): ToastInstance;
26
29
  success(message: string, duration?: number): ToastInstance;
@@ -28,6 +31,12 @@ export declare class ToastManager implements IToastManager {
28
31
  warning(message: string, duration?: number): ToastInstance;
29
32
  loading(message: string, duration?: number): ToastInstance;
30
33
  private normalizeOptions;
34
+ private normalizeConfig;
35
+ private normalizeToastOptions;
36
+ private showToasts;
37
+ private hideToasts;
38
+ private hideOne;
39
+ private notify;
31
40
  onEditorEvent(event: string, callback: (toast: ToastInstance, ...args: any[]) => void): void;
32
41
  triggerEditorEvent(event: string, toast: ToastInstance, ...args: any[]): void;
33
42
  private setupWindowFocusHandling;
@@ -1,19 +1,28 @@
1
1
  import { ToastInstance, ToastConfig } from './types';
2
+ export interface ToastQueueChanges {
3
+ show: ToastInstance[];
4
+ hide: ToastInstance[];
5
+ rejected?: ToastInstance;
6
+ }
2
7
  export declare class ToastQueue {
3
8
  private queue;
4
9
  private visible;
5
10
  private config;
6
11
  constructor(config: ToastConfig);
7
- enqueue(toast: ToastInstance): void;
8
- dequeue(id: string): boolean;
9
- private processQueue;
10
- private showToast;
11
- private hideToast;
12
- private deduplicate;
13
- updateConfig(config: Partial<ToastConfig>): void;
12
+ enqueue(toast: ToastInstance): ToastQueueChanges;
13
+ dequeue(id: string): ToastQueueChanges;
14
+ updateConfig(config: Partial<ToastConfig>): ToastQueueChanges;
14
15
  getQueued(): ToastInstance[];
15
16
  getVisible(): ToastInstance[];
16
17
  getAll(): ToastInstance[];
17
- clear(): void;
18
- forceShow(toast: ToastInstance): void;
18
+ isVisible(id: string): boolean;
19
+ clear(): ToastInstance[];
20
+ private processQueue;
21
+ private removeLowestPriorityVisible;
22
+ private removeFromCollections;
23
+ private findDuplicate;
24
+ private getDedupeKey;
25
+ private sortQueue;
26
+ private get maxVisible();
27
+ private normalizeConfig;
19
28
  }
@@ -4,11 +4,17 @@ export declare class ToastRenderer {
4
4
  private config;
5
5
  private cssInjected;
6
6
  constructor(config: ToastConfig);
7
+ updateConfig(config: ToastConfig): void;
7
8
  ensureContainer(position: ToastPosition): HTMLElement;
8
9
  createToastElement(toast: ToastInstance): HTMLElement;
9
10
  showToast(toast: ToastInstance): Promise<void>;
10
11
  hideToast(toast: ToastInstance): Promise<void>;
11
12
  updateToast(toast: ToastInstance, updates: Partial<ToastInstance['options']>): Promise<void>;
13
+ private createContent;
14
+ private createActionButton;
15
+ private applyContainerStyles;
16
+ private applyStackState;
17
+ private toCssLength;
12
18
  private pauseToast;
13
19
  private resumeToast;
14
20
  private addSwipeDismiss;
@@ -73,18 +73,24 @@ export interface ToastAction {
73
73
  label: string;
74
74
  onClick: () => void;
75
75
  primary?: boolean;
76
+ dismissOnClick?: boolean;
77
+ altText?: string;
76
78
  }
77
79
  export interface ToastProgress {
78
80
  value: number;
79
81
  showPercentage?: boolean;
80
82
  }
81
83
  export interface ToastContent {
82
- message: string;
84
+ message?: string;
85
+ title?: string;
86
+ description?: string;
83
87
  icon?: string;
84
88
  actions?: ToastAction[];
89
+ action?: ToastAction;
90
+ cancel?: ToastAction;
85
91
  progress?: ToastProgress;
86
92
  html?: boolean;
87
- render?: () => HTMLElement;
93
+ render?: (toast: ToastInstance) => HTMLElement;
88
94
  }
89
95
  export interface ToastOptions extends Partial<ToastContent> {
90
96
  id?: string;
@@ -95,6 +101,7 @@ export interface ToastOptions extends Partial<ToastContent> {
95
101
  group?: string;
96
102
  persistent?: boolean;
97
103
  closable?: boolean;
104
+ closeButton?: boolean;
98
105
  pauseOnHover?: boolean;
99
106
  pauseOnFocus?: boolean;
100
107
  swipeDismiss?: boolean;
@@ -103,6 +110,12 @@ export interface ToastOptions extends Partial<ToastContent> {
103
110
  rtl?: boolean;
104
111
  theme?: ToastTheme;
105
112
  customClass?: string;
113
+ important?: boolean;
114
+ preventDuplicate?: boolean;
115
+ dedupeKey?: string;
116
+ dedupeScope?: 'visible' | 'queue' | 'all';
117
+ ariaLive?: 'polite' | 'assertive' | 'off';
118
+ role?: 'status' | 'alert';
106
119
  animation?: AnimationConfig;
107
120
  onShow?: () => void;
108
121
  onHide?: () => void;
@@ -134,8 +147,15 @@ export interface ToastConfig {
134
147
  position: ToastPosition;
135
148
  duration: number;
136
149
  maxVisible: number;
150
+ visibleToasts?: number;
137
151
  queueStrategy: QueueStrategy;
138
152
  theme: ToastTheme;
153
+ richColors: boolean;
154
+ expand: boolean;
155
+ stack: boolean;
156
+ offset: number | string;
157
+ mobileOffset: number | string;
158
+ gap: number;
139
159
  pauseOnHover: boolean;
140
160
  pauseOnFocus: boolean;
141
161
  pauseOnWindowBlur: boolean;
@@ -144,10 +164,21 @@ export interface ToastConfig {
144
164
  dragDismiss: boolean;
145
165
  rtl: boolean;
146
166
  enableAccessibility: boolean;
167
+ closeButton: boolean;
168
+ preventDuplicate: boolean;
169
+ dedupeScope: 'visible' | 'queue' | 'all';
147
170
  container?: HTMLElement;
148
171
  zIndex?: number;
149
172
  animation?: AnimationConfig;
150
173
  }
174
+ export interface ToastState {
175
+ toasts: ToastInstance[];
176
+ visible: ToastInstance[];
177
+ queued: ToastInstance[];
178
+ groups: ToastGroup[];
179
+ config: ToastConfig;
180
+ }
181
+ export type ToastSubscriber = (state: ToastState) => void;
151
182
  export interface ToastPlugin {
152
183
  name: string;
153
184
  install: (manager: ToastManager) => void;
@@ -164,5 +195,7 @@ export interface ToastManager {
164
195
  use(plugin: ToastPlugin): void;
165
196
  getConfig(): ToastConfig;
166
197
  getToasts(): ToastInstance[];
198
+ getState(): ToastState;
199
+ subscribe(listener: ToastSubscriber): () => void;
167
200
  getGroups(): ToastGroup[];
168
201
  }