juice-toast 1.4.1 → 1.4.2

package/README.md

@@ -1,5 +1,7 @@
 # 🍹 JuiceToast
 
+> Lightweight, powerful, modern toast notification library.  
+> Zero dependencies. Promise-ready. Plugin system. Priority queue.
 
   ![npm download wekkly](https://img.shields.io/npm/dw/juice-toast)
   ![npm download](https://img.shields.io/npm/dt/juice-toast)
@@ -12,234 +14,406 @@
   ![deps](https://img.shields.io/badge/dependencies-0-brightgreen)
   ![ts](https://img.shields.io/badge/types-TypeScript-blue)
   ![last commit](https://img.shields.io/github/last-commit/KhairyK/juiceToast)
-  
+
 ---
 
+## ❓ What is JuiceToast
+
 **JuiceToast** is a lightweight, flexible, and dependency-free toast notification library for modern web applications.  
 Designed with a **clean API**, **extensive customization**, and **strong backward compatibility**, JuiceToast fits both small projects and enterprise-scale systems.
 
-It supports **ESM**, **dynamic toast types**, **theme management**, **queue handling**, and **legacy API compatibility** out of the box.
+It supports **UMD & ESM**, **dynamic toast types**, **theme management**, **queue handling**,  **legacy API compatibility**, and more.
 
 ---
 
-## ✨ Key Features
-
-- 🚀 Zero dependencies
-- 📦 Supports **ESM**
-- 🔁 Built-in queue system (one toast displayed at a time)
-- 🎨 Theme system (light, dark, and custom themes)
-- 🧩 Dynamic toast types (`success`, `error`, etc.)
-- ⏳ Auto-dismiss & sticky toasts
-- ❌ Closable toasts
-- ⭐ Icon support (position, animation, link)
-- 📐 Size presets and manual sizing
-- 🧱 Full backward compatibility with legacy APIs
+## ✨ Features
+
+- ⚡ Lightweight & fast
+- 📦 Zero dependencies
+- 🎨 Built-in themes (dark, light, glass)
+- 🧠 Promise support
+- 🔥 Priority queue (max-heap based)
+- 👆 Swipe to dismiss (mobile friendly)
+- ⏳ Animated progress bar
+- 🔁 Grouped notifications (auto counter)
+- 🎭 Avatar support
+- 🔊 Sound support
+- 🧩 Plugin system
+- ♿ Accessible (ARIA + focus/hover pause)
 
 ---
 
 ## 📦 Installation
 
+### NPM
+```bash
+npm install juice-toast
+```
+
 ### ESM
 ```js
-import juiceToast from "https://npdn.kyrt.my.id/npm/juice-toast@1.3.2dist/juice-toast.esm.js";
+import juiceToast from "https://cdn.jsdelivr.net/npm/juice-toast/dist/juice-toast.esm.js";
+```
+
+### UMD
+```html
+<script src="https://cdn.jsdelivr.net/npm/juice-toast/dist/juice-toast.umd.js"></script>
 ```
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Basic Usage
 
 ```js
-juiceToast.setup({
-  success: {
-    icon: "check",
-    theme: "light",
-    duration: 2000
-  },
-  error: {
-    icon: "x",
-    bg: "#7f1d1d",
-    color: "#fff",
-    closable: true
-  }
+juiceToast.success("Success!");
+juiceToast.error("Something went wrong!");
+juiceToast.info("Information message");
+juiceToast.warning("Warning message");
+```
+
+---
+
+## 🧠 Advanced Usage
+
+### With Title
+
+```js
+juiceToast.success({
+  title: "Success",
+  message: "Data saved successfully!"
 });
+```
+
+---
+
+### HTML Content (Sanitized)
 
-juiceToast.success("Operation completed successfully.");
-juiceToast.error({
-  title: "Error",
-  message: "An unexpected error occurred."
+```js
+juiceToast.info({
+  html: "<b>Hello</b> <i>World</i>"
 });
 ```
 
 ---
 
-## 🧠 Core Concepts
+### With Actions
+
+```js
+juiceToast.info({
+  message: "Delete this item?",
+  actions: [
+    {
+      label: "Confirm",
+      onClick: () => console.log("Confirmed"),
+      closeOnClick: true
+    }
+  ]
+});
+```
 
-### Toast Types
+---
 
-Toasts are triggered based on **types** registered using `setup()` or `addType()`.
+### With Avatar
 
 ```js
-juiceToast.info("Information message");
-juiceToast.warning({
-  message: "Proceed with caution",
-  duration: 4000
+juiceToast.success({
+  title: "New Message",
+  message: "You received a new message",
+  avatar: "https://example.com/avatar.jpg",
+  avatarPosition: "left"
 });
 ```
 
-This approach allows a clear separation between **toast configuration** and **runtime usage**.
+Positions:
+- `left`
+- `right`
+- `top`
 
 ---
 
-## ⚙️ API Reference
+### Progress Bar
+
+```js
+juiceToast.success({
+  message: "Uploading...",
+  progress: true,
+  duration: 5000
+});
+```
+
+---
 
-### `setup(config)`
-Registers all toast types and their default configuration.
+### Custom Duration
 
 ```js
-juiceToast.setup({
-  success: { bg: "green" },
-  error: { bg: "red" }
+juiceToast.info({
+  message: "Auto close in 10s",
+  duration: 10000
 });
 ```
 
 ---
 
-### `addType(name, config)`
-Adds a new toast type dynamically at runtime.
+## 🧠 Promise Support
 
 ```js
-juiceToast.addType("warning", {
-  bg: "#facc15",
-  color: "#111"
+const request = fetch("/api/data");
+
+juiceToast.promise(request, {
+  loading: "Loading...",
+  success: "Data loaded!",
+  error: "Failed to fetch",
+  timeout: 5000,
+  timeoutMessage: "Request timeout"
 });
 ```
 
 ---
 
-### `defineTheme(name, styles)`
-Creates or overrides a theme.
+## 🎨 Themes
+
+### Change Theme
 
 ```js
-juiceToast.defineTheme("ocean", {
-  bg: "#0ea5e9",
-  color: "#ffffff",
-  border: "1px solid #0284c7"
+juiceToast.setTheme("light");
+```
+
+Available:
+- `dark`
+- `light`
+- `glass`
+
+---
+
+### Custom Theme
+
+```js
+juiceToast.defineTheme("myTheme", {
+  bg: "#111",
+  color: "#fff",
+  border: "1px solid #333"
 });
+
+juiceToast.setTheme("myTheme");
 ```
 
 ---
 
-### `setTheme(name)`
-Sets the global theme.
+## 📍 Positions
 
 ```js
-juiceToast.setTheme("dark");
+juiceToast.success({
+  message: "Top Left",
+  position: "top-left"
+});
 ```
 
+Available:
+- `top-left`
+- `top-right`
+- `bottom-left`
+- `bottom-right`
+- `top-center`
+- `bottom-center`
+
 ---
 
-### `clear()`
-Clears all pending toast queues.
+## ⚡ Priority System
 
 ```js
-juiceToast.clear();
+juiceToast.success({
+  message: "Urgent message",
+  priority: "urgent"
+});
 ```
 
+Priority levels:
+- `low`
+- `normal`
+- `high`
+- `urgent`
+
+Internally powered by a max-heap queue system.
+
 ---
 
-### `destroy()`
-Removes all queues and the root DOM element.
+## 🔁 Grouped Toast
 
 ```js
-juiceToast.destroy();
+juiceToast.info({
+  message: "New notification",
+  groupId: "notifications"
+});
 ```
 
+Same `groupId` = counter increment instead of duplicate toast.
+
 ---
 
-## 🧾 Toast Payload Interface
+## 🔊 Sound Support
 
-```ts
-interface ToastPayload {
-  message?: string;
-  title?: string;
+```js
+juiceToast.setup({
+  playSound: "/sound.mp3"
+});
+```
 
-  bg?: string;
-  color?: string;
-  border?: string;
-  theme?: string;
+Per toast:
 
-  duration?: number; // milliseconds, 0 = sticky
-  position?: "top" | "center" | "bottom";
-  toast?: "top" | "center" | "bottom"; // legacy support
+```js
+juiceToast.success({
+  message: "With sound",
+  playSound: "/sound.mp3"
+});
+```
 
-  closable?: boolean;
-  closeable?: boolean; // legacy support
+---
 
-  icon?: string;
-  iconPack?: string;
-  iconLink?: string;
-  iconAnimate?: string;
-  iconPosition?: "left" | "right" | "top";
+## 🔄 Undo Support
 
-  size?: "sm" | "md" | "lg";
-  width?: string;
-  height?: string;
+```js
+juiceToast.success({
+  message: "Item deleted",
+  undo: () => console.log("Undo action"),
+  undoTimeout: 5000
+});
+```
 
-  animation?: string;
+---
 
-  actions?: {
-    label: string;
-    onClick?: (event: MouseEvent) => void;
-    closeOnClick?: boolean;
-  }[];
+## 🧩 Plugin System
 
-  [key: string]: any;
+```js
+juiceToast.use((ctx) => {
+  console.log("Toast created:", ctx);
+});
+```
+
+Plugin context:
+
+```js
+{
+  toast,
+  cfg,
+  type,
+  root
 }
 ```
 
 ---
 
-## 🔄 Backward Compatibility
-
-JuiceToast automatically maps legacy options to the modern API.
+## ⚙ Global Setup
 
-| Legacy Option | Current Option |
-|--------------|----------------|
-| `toast` | `position` |
-| `closeable` | `closable` |
-| `icon_left_top` | `icon` |
-| `icon_config` | `iconPack` |
-| `icon_onClick_url` | `iconLink` |
-| `icon_onClick_animate` | `iconAnimate` |
+```js
+juiceToast.setup({
+  duration: 3000,
+  maxVisible: 5,
+  swipeThreshold: 80,
+  glassUI: true,
+  dev: true
+});
+```
 
 ---
 
-## 🎨 Default Themes
+## 🗑 API
 
 ```js
-light: {
-  bg: "#ffffff",
-  color: "#111",
-  border: "1px solid #e5e7eb"
-}
+juiceToast.clear();    // Clear queue
+juiceToast.destroy();  // Remove all toast roots
+```
 
-dark: {
-  bg: "#1f2937",
-  color: "#ffffff",
-  border: "1px solid rgba(255,255,255,.08)"
-}
+## Modal
+
+```js
+juiceToast.modal({
+  title: "Delete File?",
+  message: "Are you sure you want to delete this file?",
+  actions: [
+    { label: "Cancel" },
+    { 
+      label: "Delete", 
+      onClick: () => console.log("Deleted!"),
+      closeOnClick: true 
+    }
+  ]
+});
 ```
 
 ---
 
-## 📌 Notes
+# 🆚 Comparison
+
+| Feature | 🍹 JuiceToast | 🌟 SweetAlert2 | 🍞 Toastify |
+|----------|---------------|---------------|-------------|
+| Zero Dependency | ✅ | ❌ | ✅ |
+| Lightweight | ✅ | ❌ (larger bundle) | ✅ |
+| Promise Integration | ✅ Built-in | ✅ | ❌ |
+| Priority Queue | ✅ | ❌ | ❌ |
+| Grouped Toast Counter | ✅ | ❌ | ❌ |
+| Plugin System | ✅ | ❌ | ❌ |
+| Swipe to Dismiss | ✅ | ❌ | ❌ |
+| Avatar Support | ✅ | ❌ | ❌ |
+| Custom Themes | ✅ | ✅ | Limited |
+| Modal Support | ✅ | ✅ | ❌ |
+| Designed for Toast Only | ✅ | ❌ (modal-focused) | ✅ |
 
-- Browser-only (DOM required)
-- Root element is automatically created: `#juice-toast-root`
-- Suitable for frameworks, custom runtimes, etc.
+### Compared to SweetAlert2
+
+SweetAlert2 is powerful and great for modal dialogs, but it's heavier and focused on popups rather than pure toast systems.
+
+JuiceToast is:
+- Smaller
+- Toast-focused
+- Queue-driven
+- Plugin-extensible
 
 ---
 
-## 📄 License
+### Compared to Toastify
+
+Toastify is simple and lightweight, but lacks:
+
+- Priority queue
+- Promise integration
+- Grouping system
+- Plugin system
+- Advanced control
+
+JuiceToast provides more advanced architecture while staying dependency-free.
+
+---
+
+# ♿ Accessibility
+
+- `role="status"`
+- Hover pause
+- Focus pause
+- Reduced motion support
+
+---
+
+# 📄 License
+
+MIT License (C) 2026 OpenDN Foundation
+
+---
+
+# ❤️ Contributing
+
+Pull requests are welcome.  
+If you find bugs, open an issue.
+
+---
+
+# 🔥 Why JuiceToast?
+
+Because simple toast libraries are boring.
 
-MIT License © OpenDN Foundation
+JuiceToast gives you:
+ - Real queue system
+ - Promise integration
+ - Plugins
+ - Advanced control
+ - Performance focus
+ - Clean modern UI

package/dist/juice-toast.d.ts

@@ -0,0 +1,150 @@
+export type ToastPosition =
+  | "top-left"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-right"
+  | "top-center"
+  | "bottom-center";
+
+export type ToastPriority = "low" | "normal" | "high" | "urgent";
+
+export type ToastSize = "sm" | "md" | "lg";
+
+export type ToastTheme = string;
+
+export interface ToastAction {
+  label?: string;
+  onClick?: (event: Event) => void;
+  closeOnClick?: boolean;
+  primary?: boolean;
+}
+
+export interface ToastOptions {
+  id?: string;
+  title?: string;
+  message?: string;
+  html?: string;
+
+  duration?: number;
+  position?: ToastPosition;
+  priority?: ToastPriority;
+  size?: ToastSize;
+
+  theme?: ToastTheme;
+
+  bg?: string;
+  color?: string;
+  border?: string;
+
+  icon?: string;
+  iconPack?: string;
+  iconSize?: string;
+  iconAnim?: string;
+  iconPosition?: "left" | "right" | "top";
+  iconLink?: string;
+  iconAnimate?: string;
+
+  avatar?: boolean | string;
+  avatarSrc?: string;
+  avatarAlt?: string;
+  avatarPosition?: "left" | "right" | "top";
+  avatarSpacing?: string;
+  avatarLazy?: boolean;
+
+  progress?: boolean;
+  progressColor?: string;
+
+  closable?: boolean;
+  closeable?: boolean;
+
+  actions?: ToastAction[];
+
+  undo?: () => void;
+  undoTimeout?: number;
+
+  groupId?: string;
+  dedupeKey?: string;
+
+  playSound?: string | null;
+}
+
+export interface PromiseStates<T = any> {
+  loading?: ToastOptions | string;
+  success?: ToastOptions | string | ((value: T) => string);
+  error?: ToastOptions | string | ((error: any) => string);
+
+  timeout?: number;
+  timeoutMessage?: string;
+  cancelMessage?: string;
+}
+
+export interface ModalOptions {
+  title?: string;
+  message?: string;
+  html?: string;
+
+  block?: boolean;
+  blur?: boolean;
+  closeOnOverlay?: boolean;
+  closable?: boolean;
+
+  animation?: "scale" | "slide" | "fade";
+  theme?: ToastTheme;
+
+  actions?: ToastAction[];
+}
+
+export interface JuiceToastDefaults {
+  duration?: number;
+  maxVisible?: number;
+  swipeThreshold?: number;
+  glassUI?: number;
+  playSound?: string | null;
+  dev?: boolean;
+  injectCSS?: boolean;
+  css?: string | null;
+}
+
+export interface JuiceToastInstance {
+  setup(config?: Record<string, ToastOptions> & JuiceToastDefaults): void;
+
+  use(plugin: (context: {
+    toast: HTMLElement;
+    cfg: ToastOptions;
+    type: string;
+    root: HTMLElement;
+  }) => void): void;
+
+  addType(name: string, config?: ToastOptions): void;
+
+  defineTheme(name: string, styles?: {
+    bg?: string;
+    color?: string;
+    border?: string;
+  }): void;
+
+  setTheme(name: string): void;
+
+  clear(): void;
+  destroy(): void;
+
+  promise<T = any>(
+    promise: Promise<T>,
+    states?: PromiseStates<T>
+  ): { cancel: () => void };
+
+  modal(options?: ModalOptions): { close: () => void };
+
+  success(options?: ToastOptions | string): void;
+  error(options?: ToastOptions | string): void;
+  info(options?: ToastOptions | string): void;
+  warning(options?: ToastOptions | string): void;
+  loading(options?: ToastOptions | string): void;
+
+  [customType: string]: any;
+}
+
+declare const juiceToast: JuiceToastInstance;
+
+export default juiceToast;
+export { juiceToast };