juice-toast 1.4.1 → 1.4.3

package/API.md

@@ -1,273 +1,318 @@
-# 🍹 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
+# UMD
 
-```js
-juiceToast.setup({
-  duration: 3000,
-  maxVisible: 3,
-  glassUI: true
-});
-
-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
+
+## `juiceToast.setup(options)`
 
-Each toast type is auto-generated from configuration or `addType`.
+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"
-}
-```
+---
 
-> `enterAnimation` respects `prefers-reduced-motion` automatically.
+# Positions
+
+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
+
+```js
+juiceToast.clear();
+```
 
-* Swipe to dismiss (touch devices)
-* Pause on hover / touch
-* Click close button (`closable: true`)
+## 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:
 
-## 🔌 Plugin System
+- `low`
+- `normal`
+- `high`
+- `urgent`
+
+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
+{
+  duration: 2500,
+  maxVisible: 3,
+  swipeThreshold: 60,
+  glassUI: 0,
+  playSound: null,
+  dev: false,
+  injectCSS: true
+}
+```
 
+# Parallax Mode
 ```js
-juiceToast.clear();   // Clear queue
-juiceToast.destroy(); // Remove all & cleanup
+juiceToast.success({
+  parallaxMode: true
+});
 ```
 
 ---
 
-## 📄 License
+# License
 
-MIT License © 2026 OpenDN Foundation
+Atrosfer 1.0 License

package/CHANGELOG.md

@@ -1,4 +1,15 @@
-## v1.4.0
+## v1.4.3
+- Add Parallax Mode
+- Fixes Animation
+- Auto-fecth **Font Awesome** Icons
+- Smart Dedup
+
+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 +19,7 @@
 
 v1.3.4
 - Bug Fixes
-- Add profile image
+- Add Avatar
 
 v1.3.3
 - Bug Fixes on Closeable Toast & Logic

package/CONTRIBUTING.md

@@ -62,4 +62,4 @@ git push origin feature/your-feature-name
 ## Code of Conduct
 Read the [Code Of Conduct](https://github.com/KhairyK/juiceToast/blob/main/CODE_OF_CONDUCT.md)
 
-2026 (C) OpenDN Foundation / Released under MIT LICENSE
+2026 (C) OpenDN Foundation / Released under Atrosfer 1.0LICENSE

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,54 +1,72 @@
-# MIT License
-
-**Project:** JuiceToast  
-**Copyright (c) 2026 OpenDN Foundation (Sholehuddin Khairy)**
-
----
-
-## Permission
-
-Permission is hereby granted, free of charge, to any person obtaining a copy  
-of this software and associated documentation files (the “Software”), to deal  
-in the Software **without restriction**, including without limitation the rights to:
-
-- use  
-- copy  
-- modify  
-- merge  
-- publish  
-- distribute  
-- sublicense  
-- and/or sell copies of the Software  
-
-and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
----
-
-## Conditions
-
-The above copyright notice and this permission notice shall be included in all  
-copies or substantial portions of the Software.
-
----
-
-## Disclaimer
-
-THE SOFTWARE IS PROVIDED **“AS IS”**, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,  
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,  
-AND NONINFRINGEMENT.
-
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES,  
-OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,  
-OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
----
-
-## Additional Notes (Project-Specific)
-
-- You are free to use JuiceToast in **personal, educational, and commercial projects**.
-- Attribution is appreciated but not required beyond the MIT notice.
-- Contributions, improvements, and community extensions are welcome.
-
----
-
-*Lightweight. Modern. Developer-friendly.*
+Atrosfer License 1.0
+
+Copyright (c) 2026 Sholehuddin Khairy
+All rights reserved.
+
+1. Grant of License:
+   - Permission is hereby granted, free of charge, to any person obtaining a copy
+     of this software and associated documentation files (the "Software"), to deal
+     in the Software without restriction, including without limitation the rights
+     to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+     copies of the Software, subject to the conditions stated herein.
+
+2. Conditions:
+   a. License Notice:
+      - The above copyright notice and this permission notice shall be included
+        in all copies or substantial portions of the Software.
+   b. Attribution:
+      - When distributing the Software in any form, credit must be given to the
+        original author, Sholehuddin Khairy, including a link to the official
+        repository or project page, if applicable.
+   c. Modifications:
+      - Any modified versions of the Software must clearly state the changes made
+        and retain this license in its entirety.
+
+3. Source Code Distribution:
+   - The Software may be distributed in source code or compiled/binary form.
+   - Redistribution must include this license and the original copyright notice.
+
+4. Commercial Use:
+   - The Software may be used for commercial purposes.
+   - Distribution or sale of modified versions for profit requires compliance
+     with all terms of this license, including proper attribution.
+
+5. Contributions:
+   - Contributions to the Software are encouraged.
+   - By submitting contributions, contributors grant the right to use, modify,
+     and distribute them under the terms of this license.
+
+6. Patent Clause:
+   - The license grants no rights to any patents owned by the copyright holder
+     or contributors. Use of the Software does not grant any patent license.
+
+7. Trademarks:
+   - This license does not grant any rights to use the trademarks, service marks,
+     or trade names of the copyright holder, except as required for reasonable
+     attribution of the Software.
+
+8. Warranty Disclaimer:
+   - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+     FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+   - THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+     LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR
+     THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+9. Indemnity:
+   - Users agree to indemnify, defend, and hold harmless the copyright holder
+     from and against any claims, damages, or liabilities arising from their
+     use, modification, or distribution of the Software.
+
+10. International Use:
+    - This license is governed by international copyright law.
+    - Use of the Software constitutes acceptance of the terms in any jurisdiction.
+
+11. Termination:
+    - Any violation of the terms of this license will result in automatic
+      termination of rights granted herein.
+    - Termination does not affect rights accrued prior to the violation.
+
+12. Acceptance:
+    - By using, copying, modifying, or distributing this Software, you acknowledge
+      that you have read, understood, and agree to be bound by the terms of this license.