customizable-toast-notification 3.20.1 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+# [4.0.0](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.20.2...v4.0.0) (2026-10-27)
+
+
+* feat!: streamline core engine to ultra-lightweight pure toast library ([8cbcc9a](https://github.com/sammy-cool/customizable-toast-notification/commit/8cbcc9a04bc86c3c6158f4f98b8c1863febd0dfc))
+
+
+### Bug Fixes
+
+* **ci:** repair audit workflow yaml syntax, prune dead overrides, and achieve 100% test coverage ([4839726](https://github.com/sammy-cool/customizable-toast-notification/commit/4839726471394701916b63dea39c107b6a49a65b))
+* fortify multi-config interactions, mobile overflow, and focus trap ([eefc61c](https://github.com/sammy-cool/customizable-toast-notification/commit/eefc61c8a2680f1d3393603a8bb52208d06e9cf4))
+
+
+### Performance Improvements
+
+* migrate rollup pipeline to native esbuild and streamline package manifests ([e3523fd](https://github.com/sammy-cool/customizable-toast-notification/commit/e3523fde7384696cc9d338b6c53c1a59878edad1))
+
+
+### BREAKING CHANGES
+
+* removed audio synthesizer, ai-scorer, spring solver,
+multi-touch pinch, and DOM pool utilities in favor of web standards.
+
+## [3.20.2](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.20.1...v3.20.2) (2026-10-27)
+
+
+### Bug Fixes
+
+* guarantee 3-character salt length in generateSalt fallback ([a21d6d6](https://github.com/sammy-cool/customizable-toast-notification/commit/a21d6d68c2c757401db5f71792f032516e5fea17))
+
 ## [3.20.1](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.20.0...v3.20.1) (2026-10-27)
 
 

package/README.md

@@ -11,7 +11,7 @@
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=sammy-cool_customizable-toast-notification&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=sammy-cool_customizable-toast-notification)
 [![Open in StackBlitz](https://img.shields.io/badge/StackBlitz-Live%20Sandbox-blue?logo=stackblitz)](https://stackblitz.com/edit/customizable-toast-notification-demo?file=index.html)
 
-**[▶ Try the interactive live playground](https://sammy-cool.github.io/customizable-toast-notification/)** — test damped spring physics, 5 zero-asset Web Audio synthesizer presets, dynamic action undo countdowns, and iOS-style card deck stacking in real time.
+**[▶ Try the interactive live playground](https://sammy-cool.github.io/customizable-toast-notification/)** — test smooth cubic-bezier physics, audio notification hooks, dynamic action undo countdowns, and iOS-style card deck stacking in real time.
 
 ```
 ┌────────────────────────────────────────────────────────────────────────┐
@@ -22,10 +22,10 @@
      ┌───────────────────┬───────────┴───────────┬───────────────────┐
      ▼                   ▼                       ▼                   ▼
 ┌──────────────┐   ┌───────────────┐     ┌───────────────┐   ┌───────────────┐
-│ Web Audio    │   │ Spring Physics│     │ Action Undo   │   │ Card Deck     │
-│ 5 Synth      │   │ Damped        │     │ Dynamic Live  │   │ iOS-Style     │
-│ Presets +    │   │ Harmonic      │     │ Countdown     │   │ Pinch-to-     │
-│ Oscilloscope │   │ Oscillator    │     │ Badge (Xs)    │   │ Expand Stack  │
+│ Sound Audio  │   │ Natural Curve │     │ Action Undo   │   │ Card Deck     │
+│ URL / Custom │   │ Cubic-Bezier  │     │ Dynamic Live  │   │ iOS-Style     │
+│ onSound Hook │   │ Spring Ease   │     │ Countdown     │   │ Expandable    │
+│ Playback     │   │ Physics       │     │ Badge (Xs)    │   │ Stacking      │
 └──────────────┘   └───────────────┘     └───────────────┘   └───────────────┘
      │                   │                       │                   │
      └───────────────────┴───────────┬───────────┴───────────────────┘
@@ -102,7 +102,7 @@ toast({
   type: "success",
   duration: 3000,
   position: "bottom-right",
-  spring: "gentle",
+  animationType: "spring",
   sound: true,
 });
 ```
@@ -116,7 +116,7 @@ Global Variable Name: `customizableToast`
 <script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification/dist/index.umd.js"></script>
 
 <!-- OR pin to a specific version -->
-<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification@3.20.1/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification@4.0.0/dist/index.umd.js"></script>
 
 <script>
   // Access the global UMD export
@@ -203,6 +203,7 @@ auto-dismissed on its own — they no-op gracefully rather than throwing. You ca
 | `showProgressBar`   | `boolean`          | `true`                          | Show countdown progress bar                                                    |
 | `animationDuration` | `string`           | `"0.4s"`                        | CSS animation duration                                                         |
 | `animationEasing`   | `string`           | `"ease"`                        | CSS animation easing function                                                  |
+| `animationType`     | `string`           | `"default"`                     | Entrance & exit animation: `"default"`, `"fade"`, `"slide"`, `"zoom"`, `"bounce"`, `"spring"`, `"flip"` |
 | `progressColor`     | `string`           | Falls back to `textColor`       | Progress bar color                                                             |
 | `progressHeight`    | `string`           | `"4px"`                         | Progress bar height                                                            |
 | `progressPosition`  | `string`           | `"bottom"`                      | Progress bar position: `"top"` or `"bottom"`                                   |
@@ -222,19 +223,19 @@ auto-dismissed on its own — they no-op gracefully rather than throwing. You ca
 | `fontPadding`       | `string`           | `undefined`                     | Custom padding for message container (e.g. `"4px 8px"`)                         |
 | `className`         | `string`           | `undefined`                     | Custom CSS class name(s) for animations / styling                              |
 | `stacked`           | `boolean`          | `false`                         | Enable iOS-style card deck stacking for multiple toasts                        |
-| `sound`             | `boolean \| string`| `false`                         | Zero-asset audio chime (`true`, `'success'`, `'error'`, `'warning'`, `'pop'`)   |
-| `soundPreset`       | `string`           | `"modern"`                      | Audio synth theme: `"modern"`, `"retro"`, `"futuristic"`, `"subtle"`, `"bell"`  |
-| `swipeToDismiss`    | `boolean`          | `true`                          | Mobile touch swipe-to-dismiss gesture with physics                             |
+| `sound`             | `boolean \| string`| `false`                         | Sound notification toggle or audio file URL (e.g. `"/chime.mp3"`)               |
+| `onSound`           | `function`         | `undefined`                     | Sound playback handler callback invoked on mount `(options) => void`           |
+| `priority`          | `number`           | `undefined`                     | Numeric queue priority (higher score displays ahead of lower priority toasts)   |
+| `swipeToDismiss`    | `boolean`          | `true`                          | Mobile touch & desktop mouse drag swipe-to-dismiss gesture                      |
 | `progressDirection` | `string`           | `"decreasing"`                  | Progress bar fill direction: `"decreasing"`, `"increasing"`, `"reverse"`, `"ltr"` |
 | `progressBarColor`  | `string`           | Falls back to `textColor`       | Alias for `progressColor` (accepts hex, rgb, hsl, CSS var)                     |
 | `progress`          | `number \| 'indeterminate'`| `undefined`            | Explicit percentage (0 to 100) or `"indeterminate"` moving gradient            |
-| `usePool`           | `boolean`          | `false`                         | Virtual element pooling for DOM recycling in high-frequency rendering           |
 | `tag` / `groupId`   | `string`           | `undefined`                     | Thread grouping identifier to replace notification in-place instead of stacking |
 | `trapFocus`         | `boolean`          | `false`                         | Modal keyboard focus trap (`Tab`/`Shift+Tab`) cycling for high-priority toasts  |
 | `shadowDom`         | `boolean`          | `false`                         | Render toast container inside isolated Shadow Root to prevent CSS bleed         |
 | `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)) |
+| `spring`            | `boolean`          | `false`                         | Natural cubic-bezier bounce curve (`cubic-bezier(0.34, 1.56, 0.64, 1)`)        |
 
 #### Position Options
 
@@ -360,41 +361,16 @@ createToast({
 | `showCountdown` | `boolean` | `true` | Decays remaining duration in seconds in real-time |
 | `onUndo` | `function` | `undefined` | Callback fired on click; supports async promises before auto-closing toast |
 
-### 🌀 Configurable Spring Physics Animation Engine
+### 🌀 Natural Spring Easing Physics
 
-Replaces standard transitions with damped harmonic oscillator physics:
+Toasts support smooth cubic-bezier physics curves with natural overshoot and settling:
 
 ```js
-// Use built-in presets: 'default', 'gentle', 'wobbly', 'stiff', 'bouncy'
+// Enable natural spring overshoot:
 createToast({
   message: "Synced to cloud",
-  spring: "bouncy",
+  spring: true, // applies cubic-bezier(0.34, 1.56, 0.64, 1) at 400ms
 });
-
-// Or customize exact physical constants:
-createToast({
-  message: "Physics simulated notification",
-  spring: {
-    stiffness: 180, // Spring tension (k)
-    damping: 12,    // Friction resistance (c)
-    mass: 1.2,      // Inertial mass (m)
-  },
-});
-```
-
-| Preset | Stiffness ($k$) | Damping ($c$) | Mass ($m$) | Behavior |
-| ------ | --------------- | ------------- | ---------- | -------- |
-| `default` | 100 | 10 | 1 | Natural subtle bounce |
-| `gentle` | 120 | 14 | 1 | Smooth with minimal overshoot |
-| `wobbly` | 180 | 12 | 1 | Playful oscillation |
-| `stiff` | 210 | 20 | 1 | Crisp, rapid settling |
-| `bouncy` | 300 | 15 | 1.2 | High energy with dynamic bounce |
-
-Register custom global presets or resolve spring curves directly:
-```js
-import { registerSpringPreset, getSpringTransition } from "customizable-toast-notification";
-
-registerSpringPreset("snappy", { stiffness: 250, damping: 22, mass: 1 });
 ```
 
 ### Loader Options
@@ -434,21 +410,29 @@ createToast({ message: "Deploy finished successfully", type: "success", stacked:
 - Hovering or keyboard-focusing on the deck automatically expands all notifications with spring animations.
 - Leaving collapses them back into a clean stack.
 
-### 🔊 Zero-Asset Web Audio API Chimes
+### 🔊 Sound Notification Playback & Hooks
 
-Play pleasant micro-feedback audio chimes generated entirely on the fly with the browser's native `AudioContext` and pure math oscillators — **zero external audio files, zero MP3 assets, and 0 network overhead**:
+Trigger sound feedback on notification mount via audio URL or custom sound handler callbacks:
 
 ```js
-import { createToast, setAudioEnabled, playTone } from "customizable-toast-notification";
+import { createToast } from "customizable-toast-notification";
 
-// Automatically chime based on type or custom tone:
-createToast({ message: "Changes saved", type: "success", sound: true }); // pleasant major chord
-createToast({ message: "Network error", type: "error", sound: "error" }); // gentle alert buzz
-createToast({ message: "Warning threshold", sound: "warning" });
-createToast({ message: "New ping", sound: "pop" });
+// 1. Play from audio URL:
+createToast({
+  message: "Changes saved",
+  type: "success",
+  sound: "/assets/sounds/success.mp3",
+});
 
-// Globally toggle sound effects (e.g. user accessibility preferences)
-setAudioEnabled(false);
+// 2. Or supply a custom onSound callback:
+createToast({
+  message: "Network warning",
+  type: "warning",
+  sound: true,
+  onSound: (options) => {
+    mySoundPlayer.play(options.type);
+  },
+});
 ```
 
 ### 👆 Mobile Touch Swipe-to-Dismiss
@@ -601,12 +585,10 @@ if (shouldReduceMotion()) {
 | `theme`                | `"light" \| "dark" \| "high-contrast" \| "compact" \| "spacious" \| "glass"` | `"light"` | Built-in CSS theme applied via `data-toast-theme` on document root.                                  |
 | `stacked`              | `boolean`                         | `false`           | Enable iOS-style 3D card deck layout with depth scaling and hover expansion.                                     |
 | `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.                                           |
+| `sound`                | `boolean`                         | `false`           | Enable sound notification support (audio URLs or `onSound` callbacks).                                            |
 | `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.                               |
+| `priorityQueue`        | `boolean`                         | `false`           | Enable 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 classifiers.                              |
 | `onMetrics`            | `((metrics: ToastMetrics) => void) \| null` | `null`  | Real-time telemetry callback emitting `{ activeCount, queueDepth, visibleCount, droppedCount, timestamp }`.      |
 | `disableInlineStyles`  | `boolean`                         | `false`           | When `true`, toasts use CSS classes instead of inline `style.*` for stricter CSP compliance.                      |
 | `reducedMotion`        | `"auto" \| "always" \| "never"`   | `"auto"`          | Control animation behavior. `"auto"` respects `prefers-reduced-motion`, `"always"` disables, `"never"` enables.  |
@@ -683,68 +665,44 @@ setConfig({ zIndex: 50000 });
 
 The following enterprise-grade features are available in v3.17.0+ and are opt-in via global config or toast options:
 
-### 🔄 Cross-Tab Toast Synchronization
+### ⚡ Priority Queue Routing
 
-Broadcast toasts to other tabs of the same application using the `BroadcastChannel` API. The first tab becomes the leader and mirrors queued / active toasts to follower tabs.
+When the queue fills (more than `maxVisible` toasts), the `priorityQueue` flag and `priority` options reorder the queue by urgency instead of strict FIFO. Priority is derived from `priority` option or `type` (error > warning > info > success), with support for custom priority scorers or consumer classifiers (`examples/ai-triage/`).
 
 ```js
-import { setConfig, createToast } from "customizable-toast-notification";
+setConfig({ priorityQueue: true });
 
-// Enable cross-tab sync globally
-setConfig({ syncTabs: true });
+createToast({ message: "Payment failed", type: "error" });   // Highest priority (score: 80)
+createToast({ message: "Background sync", type: "info" });  // Queued behind the error (score: 40)
 
-createToast({ message: "Shared across all open tabs!", type: "info" });
+// Or specify an explicit priority score:
+createToast({ message: "VIP Customer Alert", priority: 100 });
 ```
 
-Graceful degradation: if `BroadcastChannel` is unavailable (e.g. Node.js or older browsers), the library simply runs in single-tab mode — no errors.
-
-### 🧠 AI-Powered Priority Queue Routing
-
-When the queue fills (more than `maxVisible` toasts), the `aiPrioritization` flag reorders the queue by urgency instead of strict FIFO. Priority is derived from `type` (error > warning > info > success) plus keyword scoring (`urgent`, `critical`, `failed`, `done`, etc.). Fully offline, zero external calls.
-
-```js
-setConfig({ aiPrioritization: true });
-
-createToast({ message: "Payment failed", type: "error" });   // Highest priority
-createToast({ message: "Background sync", type: "info" });  // Queued behind the error
-```
+### 👆 Touch & Pointer Swipe-to-Dismiss
 
-The built-in scorer also exposes `calculateToastPriority(context)` and `categorizeToast(message)` for custom routing integrations.
+Toasts support smooth native pointer and touch swipe-to-dismiss out of the box:
 
-### 🃏 Virtual Scrolling — DOM Element Pool
-
-An internal element-pool recycles toast DOM nodes, so burst queues of 100+ toasts no longer create proportional DOM pressure or trigger layout thrashing / GC spikes. The pool size scales automatically with `MAX_VISIBLE`.
-
-No configuration required — it's transparent to callers. The queue drains in priority order (when enabled above) and reuses the same recycled elements.
-
-### 👆 Advanced Gestures: Flick Swipe & Pinch-to-Expand
-
-Swipe-to-dismiss already exists in Phase 2; Phase 3 refines the physics:
-
-- **Flick detection**: velocity ≥ 0.65 px/ms over ≥ 50 px triggers instant dismiss; anything shorter snaps back with spring easing.
-- **Pinch-to-expand**: two-finger gesture on a toast expands it to full height (useful for long error messages with stack traces); releasing collapses it back.
-
-The multi-touch math (`calculateVelocity`, `isFlick`, `detectPinch`) is exported for consumer recipes that want custom gesture behavior.
+- Horizontal drag beyond threshold flings the toast off screen with smooth dismissal transition.
+- Dragging below threshold cleanly snaps the notification back into position.
+- Interactive elements (buttons, links, inputs) inside toasts automatically guard against accidental swipe drag.
 
 ### 🏗️ How It All Fits Together
 
 ```js
-import { setConfig } from "customizable-toast-notification";
+import { setConfig, createToast } from "customizable-toast-notification";
 
 setConfig({
   maxVisible: 3,
-  syncTabs: true,        // mirror to other tabs
-  aiPrioritization: true,// sort the queue by urgency
+  priorityQueue: true,   // sort the queue by urgency
   stacked: true,         // iOS-style card deck
-  swipeToDismiss: true,  // flick physics (Phase 2)
-  sound: true,           // zero-asset Web Audio chimes (Phase 2)
+  swipeToDismiss: true,  // touch & pointer gestures
+  sound: true,           // notification chimes
 });
 
 createToast({ message: "New notification", type: "success" });
 ```
 
-The library keeps its zero-runtime-dependency guarantee: `BroadcastChannel`, Web Audio, and the gesture math are all native browser APIs with immediate graceful fallbacks when unavailable.
-
 ## 💡 Examples
 
 ### Basic Toast Types
@@ -1016,8 +974,8 @@ createToast({ message: "Using external CSS!" });
 
 ```html
 <!-- HTML (CDN) -->
-<link rel="stylesheet" href="https://unpkg.com/customizable-toast-notification@3.20.1/dist/index.css">
-<script src="https://unpkg.com/customizable-toast-notification@3.20.1/dist/index.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/customizable-toast-notification@4.0.0/dist/index.css">
+<script src="https://unpkg.com/customizable-toast-notification@4.0.0/dist/index.umd.js"></script>
 <script>
   customizableToast.setConfig({ disableInlineStyles: true });
   customizableToast.createToast({ message: "Using external CSS!" });
@@ -1263,40 +1221,6 @@ toast.info("Protected from global styles", {
 });
 ```
 
-## 🌍 Internationalization (i18n) Engine
-
-Built-in multi-locale support with automatic RTL layout switching:
-
-```javascript
-import { setLocale, registerLocale } from "customizable-toast-notification";
-
-// Built-in support for "en", "hi", "ar"
-setLocale("ar"); // Automatically switches to right-to-left layout
-
-// Register custom translations
-registerLocale("fr", {
-  undo: "Annuler",
-  close: "Fermer la notification",
-  success: "Opération réussie"
-});
-```
-
-## 📜 Notification History & Telemetry Ring Buffer
-
-Track and inspect notification delivery, dismissals, and drop telemetry:
-
-```javascript
-import { getToastHistory, clearToastHistory, setHistoryCapacity } from "customizable-toast-notification";
-
-// Set capacity (default 50)
-setHistoryCapacity(100);
-
-// Get immutable snapshot of recent toasts with timestamps, status, and metadata
-const history = getToastHistory();
-console.log(history);
-// Output: [{ id: "...", message: "...", type: "...", status: "active" | "dismissed" | "dropped", timestamp: ... }]
-```
-
 ## 🤝 Contributing
 
 Exciting times ahead! Looking for sponsors and eager to explore new collaborations:) . Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details.