juice-toast 1.4.0 → 1.4.2

package/API.md

@@ -1,273 +1,311 @@
-# 🍹 JuiceToast API Reference
+# JuiceToast API Documentation
 
-JuiceToast is a lightweight, dependency-free toast notification library with rich customization, animation, accessibility, and plugin support.
+JuiceToast is a lightweight, customizable toast notification library with support for:
+
+- Priority queue system
+- Promise handling
+- Theming
+- Plugin system
+- Grouping
+- Swipe-to-dismiss
+- Progress bar
+- Sound support
+- Avatar & Icon support
 
 ---
 
-## 📦 Installation
+# Installation
 
 ```bash
 npm install juice-toast
 ```
 
+# ESM
+
 ```js
-import juiceToast from "juice-toast";
+import juiceToast from "https://cdn.jsdelivr.net/npm/juice-toast/dist/juice-toast.esm.js";
 ```
 
----
-
-## 🚀 Quick Start
-
-```js
-juiceToast.setup({
-  duration: 3000,
-  maxVisible: 3,
-  glassUI: true
-});
+# UMD
 
-juiceToast.success({
-  title: "Success",
-  message: "Data saved successfully"
-});
+```html
+<script src="https://cdn.jsdelivr.net/npm/juice-toast/dist/juice-toast.umd.js"></script>
 ```
 
 ---
 
-## ⚙️ Global Configuration (`setup`)
+# Basic Usage
 
 ```js
-juiceToast.setup(options);
+juiceToast.success("Success message");
+juiceToast.error("Error message");
+juiceToast.info("Information");
+juiceToast.warning("Warning message");
+juiceToast.loading("Loading...");
 ```
 
-### Options
-
-| Option           | Type             | Default | Description                     |
-| ---------------- | ---------------- | ------- | ------------------------------- |
-| `duration`       | number           | `2500`  | Toast display duration (ms)     |
-| `maxVisible`     | number           | `3`     | Max visible toasts per position |
-| `glassUI`        | boolean | number | `0`     | Enable glass effect (0–100)     |
-| `playSound`      | string | null    | `null`  | Global sound file               |
-| `injectCSS`      | boolean          | `true`  | Auto inject base CSS            |
-| `css`            | string | null    | `null`  | Custom CSS override             |
-| `swipeThreshold` | number           | `60`    | Swipe distance to dismiss       |
-| `dev`            | boolean          | `false` | Enable console warnings         |
-
 ---
 
-## 🧩 Toast Methods
+# Global Configuration
 
-Each toast type is auto-generated from configuration or `addType`.
+## `juiceToast.setup(options)`
+
+Configure global defaults.
 
 ```js
-juiceToast.success(payload);
-juiceToast.error(payload);
-juiceToast.info(payload);
-juiceToast.warning(payload);
-juiceToast.loading(payload);
+juiceToast.setup({
+  duration: 3000,
+  maxVisible: 5,
+  swipeThreshold: 80,
+  injectCSS: true,
+  dev: true
+});
 ```
 
-Payload can be a **string** or **object**.
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|----------|-------------|
+| duration | number | 2500 | Default auto-dismiss duration (ms) |
+| maxVisible | number | 3 | Maximum visible toasts per position |
+| swipeThreshold | number | 60 | Swipe distance required to dismiss |
+| injectCSS | boolean | true | Automatically inject base CSS |
+| css | string | internal | Custom CSS override |
+| dev | boolean | false | Enable debug logs |
+| playSound | string | null | Sound URL |
 
 ---
 
-## 📝 Toast Payload Options
+# Toast Methods
 
-### Basic
+Each toast type can accept:
 
 ```js
-{
-  title: "Title",
-  message: "Message",
-  duration: 3000
-}
+juiceToast.success(options)
 ```
 
-### Appearance
+Or shortcut:
 
 ```js
-{
-  theme: "dark",
-  bg: "#333",
-  color: "#fff",
-  border: "1px solid #000",
-  size: "sm" | "md" | "lg",
-  compact: true
-}
+juiceToast.success("Message")
 ```
 
 ---
 
-## 🎬 Animation
+# Toast Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| message | string | Main text |
+| title | string | Toast title |
+| html | string | Render sanitized HTML |
+| duration | number | Auto close duration |
+| position | string | Toast position |
+| theme | string | Theme name |
+| icon | string | Icon class |
+| iconPack | string | Icon library prefix |
+| iconAnim | string | Icon animation class |
+| iconSize | string | Icon font size |
+| avatar | string | Avatar image URL |
+| avatarAlt | string | Avatar alt text |
+| avatarPosition | left/right/top | Avatar position |
+| closable | boolean | Show close button |
+| progress | boolean | Show progress bar |
+| progressColor | string | Custom progress color |
+| actions | array | Custom buttons |
+| undo | function | Undo callback |
+| undoTimeout | number | Timeout before auto-close |
+| groupId | string | Group multiple toasts |
+| dedupeKey | string | Prevent duplicate toasts |
+| priority | low/normal/high/urgent | Priority queue level |
+| playSound | string | Override sound |
 
-```js
-{
-  animation: "slide-in" | "fade-in" | "bounce-in",
-  enterAnimation: "pop" | "bounce" | "shake" | "wiggle" | "pulse" | "spin"
-}
-```
+---
+
+# Positions
 
-> `enterAnimation` respects `prefers-reduced-motion` automatically.
+Available positions:
+
+- `top-left`
+- `top-right`
+- `bottom-left`
+- `bottom-right`
+- `top-center`
+- `bottom-center`
+
+Default: `bottom-right`
 
 ---
 
-## 🧊 Glass UI
+# Themes
+
+Built-in themes:
+
+- `dark`
+- `light`
+- `glass`
+
+## Define Custom Theme
 
 ```js
-{
-  glassUI: true        // default intensity (60)
-  glassUI: 80          // custom intensity
-}
+juiceToast.defineTheme("custom", {
+  bg: "#111",
+  color: "#fff",
+  border: "1px solid #333"
+});
 ```
 
----
-
-## 📍 Position / Placement
+## Set Theme
 
 ```js
-{
-  position: "top-left" |
-            "top-right" |
-            "top-center" |
-            "bottom-left" |
-            "bottom-right" |
-            "bottom-center"
-}
+juiceToast.setTheme("custom");
 ```
 
 ---
 
-## 🎯 Icon System
+# Custom Toast Types
+
+## `juiceToast.addType(name, config)`
 
 ```js
-{
-  icon: "check-circle",
-  iconPack: "fa fa-solid",
-  iconSize: "18px",
-  iconPosition: "left" | "right" | "top",
-  iconAnimate: "bounce",
-  iconLink: "https://example.com"
-}
+juiceToast.addType("custom", {
+  bg: "#9333ea",
+  icon: "fa-star",
+  duration: 5000
+});
+
+juiceToast.custom("Hello!");
 ```
 
 ---
 
-## 🔘 Actions Button
+# Promise Toast
+
+## `juiceToast.promise(promise, options)`
 
 ```js
-{
-  actions: [
-    {
-      label: "Undo",
-      onClick: () => {},
-      closeOnClick: true
-    }
-  ]
-}
+juiceToast.promise(fetch("/api"), {
+  loading: "Loading...",
+  success: "Success!",
+  error: "Failed",
+  timeout: 5000,
+  timeoutMessage: "Request timeout"
+});
 ```
 
----
-
-## ⏳ Progress Bar
+### Returns
 
 ```js
 {
-  progress: true,
-  progressColor: "rgba(255,255,255,.7)"
+  cancel: Function
 }
 ```
 
 ---
 
-## 🔊 Sound
+# Plugin System
+
+## `juiceToast.use(pluginFunction)`
 
 ```js
-{
-  playSound: "ding.mp3"
-}
+juiceToast.use(({ toast, cfg, type, root }) => {
+  console.log("Toast created:", type);
+});
 ```
 
-Supported formats: `.mp3`, `.wav`, `.ogg`, `.opus`, `.aiff`, `.wma`
-
 ---
 
-## ✋ Interaction
+# Queue Management
+
+## Clear Queue
 
-* Swipe to dismiss (touch devices)
-* Pause on hover / touch
-* Click close button (`closable: true`)
+```js
+juiceToast.clear();
+```
+
+## Destroy All Toast Roots
 
 ```js
-{ closable: true }
+juiceToast.destroy();
 ```
 
 ---
 
-## ♿ Accessibility (A11Y)
+# Advanced Features
 
-* `role="alert"`
-* `aria-live="polite"`
-* Keyboard focusable
-* Reduced motion support
+## Priority Queue
 
----
+Available priorities:
+
+- `low`
+- `normal`
+- `high`
+- `urgent`
 
-## 🔌 Plugin System
+Example:
 
 ```js
-juiceToast.use(ctx => {
-  const { toast, cfg, type, root } = ctx;
+juiceToast.success({
+  message: "Important",
+  priority: "urgent"
 });
 ```
 
 ---
 
-## 🎨 Theme API
+## Grouped Toast
 
 ```js
-juiceToast.defineTheme("ocean", {
-  bg: "#0ea5e9",
-  color: "#fff"
+juiceToast.info({
+  message: "Grouped",
+  groupId: "network"
 });
-
-juiceToast.setTheme("ocean");
 ```
 
 ---
 
-## ➕ Custom Toast Type
+## Action Buttons
 
 ```js
-juiceToast.addType("custom", {
-  icon: "star",
-  bg: "gold",
-  color: "#000"
+juiceToast.success({
+  message: "Saved",
+  actions: [
+    {
+      label: "Undo",
+      onClick: () => console.log("Undo"),
+      closeOnClick: true
+    }
+  ]
 });
-
-juiceToast.custom("Hello World");
 ```
 
 ---
 
-## Background image
-```js
-juiceToast.setup({
-  image: { bgImage: "https://cdn.kyrt.my.id/image/ts-logo-128.svg" }
-});
+# Accessibility
 
-juiceToast.image("Hi");
-```
+- Uses `role="status"`
+- Keyboard focus support
+- Pause on hover & focus
+- Swipe support (touch & mouse)
 
 ---
 
-## 🧹 Utilities
+# Internal Defaults
 
 ```js
-juiceToast.clear();   // Clear queue
-juiceToast.destroy(); // Remove all & cleanup
+{
+  duration: 2500,
+  maxVisible: 3,
+  swipeThreshold: 60,
+  glassUI: 0,
+  playSound: null,
+  dev: false,
+  injectCSS: true
+}
 ```
 
 ---
 
-## 📄 License
+# License
 
-MIT License © 2026 OpenDN Foundation
+MIT License

package/CHANGELOG.md

@@ -1,4 +1,9 @@
-## v1.4.0
+## v1.4.2
+- Add modal
+- Bug fixes
+- improve documentation
+
+v1.4.0 / v1.4.1
 - Add Smart Queue
 - Bugs fixed & Logic fixes
 - Fix the toast speed
@@ -8,7 +13,7 @@
 
 v1.3.4
 - Bug Fixes
-- Add profile image
+- Add Avatar
 
 v1.3.3
 - Bug Fixes on Closeable Toast & Logic

package/EoL.md

@@ -1,12 +1,42 @@
-## End of Life (EoL) Notice
-
-The following versions and distributions have reached End of Life (EoL) and are no longer maintained.
-
-| EoL Version        | Affected Target | Reason |
-|--------------------|-----------------|--------|
-| 1.2.1              | None            | This version is End of Support, update to ^1.3.0 |
-| 1.2.0-rc.2026      | UMD build       | UMD distribution has been removed to simplify maintenance and reduce build complexity |
-| 0.0.1-next.1202026 | None            | This next version are ended, use Release Candidate version |
-| 0.0.0-next.1202026 | Pre-release tag | Versioning structure became inconsistent and difficult to maintain |
-| 1.1.0              | None            | This version is End of Support, update to ^1.2.0 |
-| 1.0.0 | Unstable release | Deprecated due to outdated internal architecture and styling standards |
+# End of Life (EoL) & End of Support (EoS) Notice
+
+This document outlines versions that are no longer maintained.
+
+---
+
+## 🔴 End of Life (EoL)
+
+The following versions are fully discontinued and **should not be used in production**.
+
+| Version | Affected Target | Replacement | Reason |
+|----------|----------------|------------|--------|
+| 1.4.0 | Distribution files | 1.4.1 | Distribution files were unintentionally identical to v1.3.4 |
+| 1.2.0-rc.2026 | UMD build | ^1.3.0 | UMD distribution was removed to simplify maintenance and reduce build complexity |
+| 0.0.0-next.1202026 | Pre-release tag | 0.0.1-next.1202026 or stable releases | Versioning structure became inconsistent and difficult to maintain |
+| 1.0.0 | Entire release | ^1.2.0 | Deprecated due to legacy architecture that does not meet current stability and performance standards |
+
+---
+
+## 🟡 End of Support (EoS)
+
+The following versions remain functional but **will no longer receive updates, fixes, or improvements**.
+
+| Version Range | Replacement | Notes |
+|---------------|------------|-------|
+| 1.3.x | 1.3.4 (LTS) or ^1.4.x | Maintenance has ended for this minor series |
+| 1.2.1 | ^1.3.0 | Superseded by newer improvements and fixes |
+| 1.1.0 | ^1.2.0 | Maintenance discontinued |
+| 0.0.1-next.1202026 | Release Candidate or stable releases | Pre-release cycle has ended |
+
+---
+
+## 📌 Recommendation
+
+Users are strongly encouraged to upgrade to the latest stable version to ensure:
+
+- Improved performance
+- Ongoing security updates
+- Bug fixes and stability improvements
+- Better long-term compatibility
+
+For migration guidance, please refer to the official documentation or release notes.

package/LICENSE.md

@@ -1,7 +1,7 @@
 # MIT License
 
 **Project:** JuiceToast  
-**Copyright (c) 2026 OpenDN Foundation (Sholehuddin Khairy)**
+**Copyright (c) 2026 OpenDN Foundation (Sholehuddin Khairy / KhairyK)**
 
 ---