customizable-toast-notification 3.19.0 → 3.20.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+# [3.20.0](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.19.0...v3.20.0) (2026-10-26)
+
+
+### Bug Fixes
+
+* **core:** resolve cta double-click, rtl button margins, dynamic stacked, and cross-tab update sync ([0d1eb0f](https://github.com/sammy-cool/customizable-toast-notification/commit/0d1eb0f9390b2076c6642108df188566f3e40f27))
+* **core:** resolve rtl layout, localized labels, fade exit timing, and drop telemetry ([6477abb](https://github.com/sammy-cool/customizable-toast-notification/commit/6477abb4d4b3f564c15ad8e302c3e41e9dacd2c9))
+* handle floating promises to satisfy sonarqube quality gate ([8ee9b3b](https://github.com/sammy-cool/customizable-toast-notification/commit/8ee9b3b7b546bdad8b4542f0beddbdb80ea9a762))
+* update SonarQube organization and project key for consistency ([a730b5f](https://github.com/sammy-cool/customizable-toast-notification/commit/a730b5f97e2351c3e27d6cf40a019d3a71aa0b2a))
+
+
+### Features
+
+* **core:** implement history ring buffer, tag threading, focus trap, and framework adapters ([8f4f362](https://github.com/sammy-cool/customizable-toast-notification/commit/8f4f3623412aea01c2d8b851363463e5fc8bf11a))
+* **core:** implement i18n engine, react adapter, multi-tab queue sync, and a11y ([6aa44f6](https://github.com/sammy-cool/customizable-toast-notification/commit/6aa44f6cebfef164c1098c7af510934578212ebc))
+
 # [3.19.0](https://github.com/sammy-cool/customizable-toast-notification/compare/v3.18.2...v3.19.0) (2026-10-24)
 
 

package/README.md

@@ -7,6 +7,8 @@
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/customizable-toast-notification)](https://bundlephobia.com/package/customizable-toast-notification)
 [![TypeScript Strict](https://img.shields.io/badge/TypeScript-Strict%20Types-blue?logo=typescript)](dist/index.d.ts)
 [![CodeQL Security](https://img.shields.io/badge/CodeQL-Protected-success?logo=github)](.github/workflows/codeql.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=sammy-cool_customizable-toast-notification&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=sammy-cool_customizable-toast-notification)
+[![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.
@@ -34,13 +36,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 177 automated unit & logic tests plus Playwright cross-browser specifications.
+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 233 automated unit & logic tests plus 80 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** - 177 real logic & unit tests plus Playwright end-to-end specifications across Chromium, Firefox, and WebKit — not just "it worked on my machine"
+- ✅ **Rigorously Tested** - 233 real logic & unit tests across 87 suites plus 80 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
@@ -114,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.19.0/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/customizable-toast-notification@3.20.0/dist/index.umd.js"></script>
 
 <script>
   // Access the global UMD export
@@ -227,6 +229,9 @@ auto-dismissed on its own — they no-op gracefully rather than throwing. You ca
 | `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)) |
@@ -1011,8 +1016,8 @@ createToast({ message: "Using external CSS!" });
 
 ```html
 <!-- HTML (CDN) -->
-<link rel="stylesheet" href="https://unpkg.com/customizable-toast-notification@3.19.0/dist/index.css">
-<script src="https://unpkg.com/customizable-toast-notification@3.19.0/dist/index.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/customizable-toast-notification@3.20.0/dist/index.css">
+<script src="https://unpkg.com/customizable-toast-notification@3.20.0/dist/index.umd.js"></script>
 <script>
   customizableToast.setConfig({ disableInlineStyles: true });
   customizableToast.createToast({ message: "Using external CSS!" });
@@ -1192,6 +1197,106 @@ document.documentElement.style.setProperty('--toast-success-bg', '#10b981');
 --toast-emergency-z-index: 10099; /* Emergency fallback z-index */
 ```
 
+## 🧩 First-Class Framework Subpath Adapters
+
+Native, zero-runtime-overhead subpaths with complete TypeScript typings are included for modern web frameworks:
+
+```typescript
+// React & Next.js
+import { useToast } from "customizable-toast-notification/react";
+const { success, error, promise } = useToast();
+
+// Vue 3 & Nuxt
+import { useToast } from "customizable-toast-notification/vue";
+const toast = useToast();
+toast.success("Saved!");
+
+// Svelte & SvelteKit
+import { toastStore } from "customizable-toast-notification/svelte";
+$toastStore.info("Store updated");
+
+// SolidJS
+import { useToast } from "customizable-toast-notification/solid";
+const { success } = useToast();
+
+// Angular 17+ (Signals & Standalone Injectable)
+import { injectToast, ToastService } from "customizable-toast-notification/angular";
+const toast = injectToast();
+```
+
+## 🧵 Threaded Tag Grouping (`tag` / `groupId`)
+
+Replace or update notifications in-place by tag instead of stacking duplicate cards:
+
+```javascript
+// Updates the existing 'upload-123' card in-place and resets the timer
+toast({
+  tag: "upload-123",
+  message: "Uploading: 45%...",
+  showProgressBar: true,
+  progress: 45
+});
+```
+
+## 🔒 Accessible Modal Keyboard Focus Trap (`trapFocus`)
+
+Trap keyboard navigation (`Tab` / `Shift+Tab`) inside high-priority interactive dialogs or action confirmations:
+
+```javascript
+toast.error("Critical: Unsaved changes will be lost", {
+  trapFocus: true,
+  role: "alert",
+  cta: [
+    { label: "Discard", onClick: () => discardChanges() },
+    { label: "Keep Editing", onClick: () => {} }
+  ]
+});
+```
+
+## 🛡️ Shadow DOM Isolation (`shadowDom`)
+
+Render notifications in an isolated Shadow Root to prevent host application CSS collisions:
+
+```javascript
+toast.info("Protected from global styles", {
+  shadowDom: true
+});
+```
+
+## 🌍 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.