customizable-toast-notification 3.16.0 → 3.17.0

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+# [3.17.0](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.16.0...v3.17.0) (2026-10-10)
+
+
+### Bug Fixes
+
+* **a11y:** preserve default role=alert while supporting custom role and live region updates ([fc5108c](https://github.com/sammy-cool/customizable-toast-notification/commit/fc5108ca487a14fae2277bb040579bced5b83a40))
+* **arch:** fortify aria-live transitions, per-cta styling, and shorthand exports ([accce90](https://github.com/sammy-cool/customizable-toast-notification/commit/accce901d656250365b5a9fac7a5a95aa1fa132a))
+* **dx:** sync preset clicks, format multi-CTA code, and automate CDN purge ([579cede](https://github.com/sammy-cool/customizable-toast-notification/commit/579cede1df912ca9ee8bcfa44e0c1bf342f44fba))
+* **e2e:** fix desktop swipe boundary in Firefox and enhance playground ([a37d61a](https://github.com/sammy-cool/customizable-toast-notification/commit/a37d61ac9e4e66dfc2f1d41f743565527b362321))
+* harden priority routing, leader sync, element pool, and touch tracking ([a9c45d1](https://github.com/sammy-cool/customizable-toast-notification/commit/a9c45d189448c885a9c791ef611ba2ad8956ba74))
+* **playground:** attach fallback onUndo callback in fireCurrentConfig ([fcb9040](https://github.com/sammy-cool/customizable-toast-notification/commit/fcb9040408f36a00d8bf3155caba526b15322621))
+* resolve 50+ bugs across shorthands, gestures, accessibility, and styling ([6059bab](https://github.com/sammy-cool/customizable-toast-notification/commit/6059babef3e89ac5a9079ac07d9f0da4806fed9a))
+* **security:** handle data: scheme in URL check and synchronize lockfile ([62ac7da](https://github.com/sammy-cool/customizable-toast-notification/commit/62ac7da21e2d2054ca4aaaabcb50ee7596a9f6ee))
+* **security:** neutralize invalid link href to safe hash instead of removing attribute ([3f934c5](https://github.com/sammy-cool/customizable-toast-notification/commit/3f934c5f8bc36f927a50eb4214fe1a222bb3d4e5))
+* **security:** resolve CodeQL DOM XSS alerts and harden workflow scanner configuration ([70dc0ba](https://github.com/sammy-cool/customizable-toast-notification/commit/70dc0ba2a1dc30f77b9455c924388472fdc2c1a2))
+* **security:** resolve CodeQL polynomial regex alerts and upgrade vulnerable dev dependencies ([a3570c3](https://github.com/sammy-cool/customizable-toast-notification/commit/a3570c3056261659f3fca4565cf7b6d539d5f6a7))
+* support center position aliases, global swipeToDismiss, and full RTL layout ([1960564](https://github.com/sammy-cool/customizable-toast-notification/commit/196056457dab55b4e990b4817990f7835c9d1ae4))
+* **touch:** prevent swipe-to-dismiss gesture when clicking interactive elements ([e17c293](https://github.com/sammy-cool/customizable-toast-notification/commit/e17c29378631e9a6e9dd4b4de774d369c0b36f47))
+* **ux:** auto-dismiss resolved loading toasts and synchronize options state in update ([43c1252](https://github.com/sammy-cool/customizable-toast-notification/commit/43c1252b2270f0f85728aee4e819a8eec9705fd3))
+* **ux:** fix animation timing reflow and audio autoplay browser warning ([28d8e80](https://github.com/sammy-cool/customizable-toast-notification/commit/28d8e805979f740ced660316a11482228f502f10))
+* **ux:** synchronize undo countdown badge with pauseOnHover and keyboard focus ([4eaeee2](https://github.com/sammy-cool/customizable-toast-notification/commit/4eaeee2fda37e0a44e29a91fdbd32c9e16beb42a))
+
+
+### Features
+
+* **cta:** support in-place CTA streaming updates and harden insertion order ([062bb37](https://github.com/sammy-cool/customizable-toast-notification/commit/062bb3711877e9f13de6fc808c95aebbbd3c6d64))
+* **dx:** add ergonomic shorthand methods and direct string message support ([7cc7669](https://github.com/sammy-cool/customizable-toast-notification/commit/7cc7669e0432d214ace48066bba2e6295717e2f3))
+* **dx:** support default ESM export, persistent loading shorthand, and programmatic dismiss ([a9e13cc](https://github.com/sammy-cool/customizable-toast-notification/commit/a9e13cc95661459fb3974e41d9d4e956f8d02040))
+* **dx:** wire shorthands into framework guides and fix update pause ([df070ae](https://github.com/sammy-cool/customizable-toast-notification/commit/df070aefb4ff0d1c50645ad5ba2d75f16cb9bce3))
+* **playground:** add interactive secondary CTA controls and harden timer test bounds ([c23c032](https://github.com/sammy-cool/customizable-toast-notification/commit/c23c032f32a675300ee870ae8d72f744593efd12))
+* **recipes:** add SaaS notification center history tray and tab alerting recipes ([6b80c55](https://github.com/sammy-cool/customizable-toast-notification/commit/6b80c550fbf53848d8299fd7a1fbbf544c525489))
+* **ui,ux,dx:** add built-in SVG icons, pause shimmer, hotkeys, and adapters ([cab6096](https://github.com/sammy-cool/customizable-toast-notification/commit/cab609652c7c639e75778e39fedd40de3f56fe81))
+* **undo:** support in-place undo action streaming and ordered DOM insertion ([bcdb168](https://github.com/sammy-cool/customizable-toast-notification/commit/bcdb16839e1465e4d42ec47b831ca913f4dbe858))
+
 # [3.16.0](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.15.0...v3.16.0) (2026-10-08)
 
 

package/README.md

@@ -34,13 +34,13 @@
            └──────────────────────────────────────────────────┘
 ```
 
-Toast notifications that work the same everywhere — plain JavaScript, Vue, Svelte, Angular, SolidJS, or a multi-page app. Built with sanitized-by-default HTML rendering, zero runtime dependencies, and 132 automated unit & end-to-end tests across Chromium, Firefox, and WebKit.
+Toast notifications that work the same everywhere — plain JavaScript, Vue, Svelte, Angular, SolidJS, or a multi-page app. Built with sanitized-by-default HTML rendering, zero runtime dependencies, and 177 automated unit & logic tests plus Playwright cross-browser specifications.
 
 ## ✨ Key Features
 
 - 🌐 **Actually Framework Agnostic** - Not a React library with "vanilla JS support" bolted on — the same API works identically in React, Vue, Angular, Svelte, htmx, or plain HTML with no build step at all
 - 🛡️ **Sanitized by Default** - `allowHtml` content is sanitized before render (DOMPurify if it's on the page, a verified-equivalent fallback if not) — safe to use with content you don't fully control
-- ✅ **Rigorously Tested** - 129 real Playwright end-to-end tests across Chromium, Firefox, and WebKit, plus a fast unit suite — not just "it worked on my machine"
+- ✅ **Rigorously Tested** - 177 real logic & unit tests plus Playwright end-to-end specifications across Chromium, Firefox, and WebKit — not just "it worked on my machine"
 - 🚫 **Zero Runtime Dependencies** - Nothing pulled in when your users load your app
 - 🔧 **Real TypeScript Types** - Full type definitions with real autocomplete and type-checking, not a placeholder `any`
 - 🎨 **Highly Customizable** - Colors, positions, animations, progress bars, and styling
@@ -72,21 +72,40 @@ yarn add customizable-toast-notification
 ### ES Modules
 
 ```js
-import {
-  createToast,
-  setDefaultColors,
-  setDefaultMessages,
-} from "customizable-toast-notification";
-
-// Simple usage
-createToast({
-  message: "Hello World!",
+// Default import (recommended) or named import:
+import toast, { createToast } from "customizable-toast-notification";
+
+// 1. Shorthand methods (Quickest & cleanest)
+toast.success("Saved successfully!");
+toast.error("Failed to connect to server");
+toast.warning("Unsaved changes detected");
+toast.info("Tip: Press Esc to dismiss anytime");
+toast.custom("<b>Formatted</b> notification with HTML!");
+
+// 2. Persistent loading state
+const loading = await toast.loading("Uploading files...");
+// ... later update in-place
+await loading.update({ type: "success", message: "Files uploaded!", showLoader: false });
+
+// 3. Direct message string
+toast("Simple notification");
+
+// 4. Programmatic dismiss
+toast.dismiss(loading.id); // dismiss by ID or handle
+toast.dismissAll();        // dismiss all notifications
+
+// 5. Full configuration options
+toast({
+  message: "Customized toast!",
   type: "success",
   duration: 3000,
+  position: "bottom-right",
+  spring: "gentle",
+  sound: true,
 });
 ```
 
-### CDN/Browser (UMD Build) / Quick Try with jsDelivr
+### CDN / Browser (UMD Build) / Quick Try with jsDelivr
 
 Global Variable Name: `customizableToast`
 
@@ -94,8 +113,8 @@ Global Variable Name: `customizableToast`
 <!-- Always latest version -->
 <script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification/dist/index.umd.js"></script>
 
-<!-- OR pin to a specific version (recommended for stability) -->
-<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification@3.12.3/dist/index.umd.js"></script>
+<!-- OR pin to a specific version -->
+<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification@3.16.0/dist/index.umd.js"></script>
 
 <script>
   // Access the global UMD export
@@ -135,13 +154,28 @@ const handle = await createToast({
 // Update progress in-place:
 await handle.update({ progress: 65, message: "Uploading assets... 65%" });
 
-// Transition state seamlessly:
+// Stream multi-action CTA buttons dynamically:
+await handle.update({
+  message: "Upload requires authorization:",
+  cta: [
+    { label: "Approve", onClick: () => console.log("Approved!") },
+    { label: "Cancel", autoClose: true, onClick: () => console.log("Cancelled") },
+  ],
+});
+
+// Transition to completion with dynamic countdown Undo badge:
 await handle.update({
   type: "success",
   message: "Upload complete!",
   showLoader: false,
-  duration: 3000,
+  cta: null, // cleanly strip CTA buttons
+  duration: 6000,
   sound: "success",
+  undo: {
+    label: "Undo",
+    showCountdown: true, // "Undo (6s... 1s)"
+    onUndo: () => console.log("Undone!"),
+  },
 });
 
 // Or dismiss manually at any point:
@@ -149,7 +183,8 @@ await handle.dismiss();
 ```
 
 `handle.dismiss()` and `handle.update()` are always safe to call, even if the toast already
-auto-dismissed on its own — they no-op gracefully rather than throwing.
+auto-dismissed on its own — they no-op gracefully rather than throwing. You can update `message`,
+`progress`, `type`, `showLoader`, `loader`, `cta` (single object, array, or `null`), and `undo` in-place.
 
 #### Options
 
@@ -180,6 +215,7 @@ auto-dismissed on its own — they no-op gracefully rather than throwing.
 | `fontLineHeight`    | `string`           | `"1.4"`                         | Font line height                                                               |
 | `showLoader`        | `boolean`          | `false`                         | Show spinner loader before the message                                         |
 | `loader`            | `object`           | `null`                          | Custom loader config (`size`, `color`, `text`)                                 |
+| `icon`              | `boolean \| string \| HTMLElement` | `true` for typed, `null` | Status icon: `true` (built-in SVG), `false` (hide), emoji (`"🎉"`), SVG string, or DOM node |
 | `fontDirection`     | `string`           | `"auto"`                        | Font direction: `"auto"`, `"ltr"`, `"rtl"`                                     |
 | `fontPadding`       | `string`           | `undefined`                     | Custom padding for message container (e.g. `"4px 8px"`)                         |
 | `className`         | `string`           | `undefined`                     | Custom CSS class name(s) for animations / styling                              |
@@ -189,7 +225,7 @@ auto-dismissed on its own — they no-op gracefully rather than throwing.
 | `swipeToDismiss`    | `boolean`          | `true`                          | Mobile touch swipe-to-dismiss gesture with physics                             |
 | `progress`          | `number`           | `undefined`                     | Explicit progress bar percentage (0 to 100)                                    |
 | `usePool`           | `boolean`          | `false`                         | Virtual element pooling for DOM recycling in high-frequency rendering           |
-| `cta`               | `object`           | `null`                          | Call-to-action configuration (see [CTA](#call-to-action))                      |
+| `cta`               | `object \| array`   | `null`                          | Call-to-action configuration (see [CTA](#call-to-action))                      |
 | `undo`              | `function \| object`| `null`                         | Action Undo button with live dynamic countdown badge (see [Undo](#️-action-undo-with-live-countdown)) |
 | `spring`            | `boolean \| string \| object`| `null`                | Configurable spring physics animations (see [Spring Physics](#-configurable-spring-physics-animation-engine)) |
 
@@ -199,8 +235,9 @@ auto-dismissed on its own — they no-op gracefully rather than throwing.
 // Corner positions
 - "top-left", "top-right", "bottom-left", "bottom-right"
 
-// Edge positions
+// Edge positions & center aliases
 - "top-center", "bottom-center", "left-center", "right-center"
+- "center-top", "center-bottom", "center-left", "center-right"
 
 // Full width
 - "top-full-width", "bottom-full-width"
@@ -559,6 +596,7 @@ if (shouldReduceMotion()) {
 | `swipeToDismiss`       | `boolean`                         | `true`            | Enable touch / mouse drag swipe gesture to dismiss toasts with spring snap-back physics.                         |
 | `sound`                | `boolean`                         | `true`            | Enable pure Web Audio API notification chimes (0KB network, zero audio assets).                                   |
 | `soundPreset`          | `"modern" \| "retro" \| "futuristic" \| "subtle" \| "bell"` | `"modern"` | Built-in sound synthesis theme for audio notifications.                                           |
+| `pauseOnHover`         | `boolean`                         | `false`           | When `true`, automatically pauses countdown timers for all toasts on mouse hover or keyboard focus.               |
 | `syncTabs`             | `boolean`                         | `false`           | Synchronize toast notifications across browser tabs using BroadcastChannel.                                      |
 | `aiPrioritization`     | `boolean`                         | `false`           | Enable offline content-aware queue priority sorting (critical alerts jump ahead of routine messages).            |
 | `priorityScorer`       | `((context) => number) \| null`   | `null`            | Custom priority scoring function for custom business logic or external AI models.                               |
@@ -636,7 +674,7 @@ setConfig({ zIndex: 50000 });
 
 ## 🚀 Phase 3: Advanced Features
 
-The following enterprise-grade features are available in v3.15.0+ and are opt-in via global config or toast options:
+The following enterprise-grade features are available in v3.16.0+ and are opt-in via global config or toast options:
 
 ### 🔄 Cross-Tab Toast Synchronization
 
@@ -971,8 +1009,8 @@ createToast({ message: "Using external CSS!" });
 
 ```html
 <!-- HTML (CDN) -->
-<link rel="stylesheet" href="https://unpkg.com/customizable-toast-notification@3.15.0/dist/index.css">
-<script src="https://unpkg.com/customizable-toast-notification@3.15.0/dist/index.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/customizable-toast-notification@3.16.0/dist/index.css">
+<script src="https://unpkg.com/customizable-toast-notification@3.16.0/dist/index.umd.js"></script>
 <script>
   customizableToast.setConfig({ disableInlineStyles: true });
   customizableToast.createToast({ message: "Using external CSS!" });