layerpro 1.5.1 → 2.0.0

package/README.md

@@ -1,49 +1,67 @@
-# [LayerPro](https://npmjs.com/package/layerpro)
+# LayerPro 🚀
 
-![layerpro](https://raw.githubusercontent.com/passariello/container/be0611e9bead336dcec32d522d103e7e3661f502/layerpro/assets/logos/logo.svg)
+<div align="center">
 
-[![version](https://img.shields.io/npm/v/layerpro.svg)](https://npmjs.org/package/layerpro)
-[![downloads](https://img.shields.io/npm/dm/layerpro.svg)](https://npmjs.org/package/layerpro)
+![LayerPro](https://raw.githubusercontent.com/passariello/container/be0611e9bead336dcec32d522d103e7e3661f502/layerpro/assets/logos/logo.svg)
 
-[![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/layerpro)
+[![Version](https://img.shields.io/npm/v/layerpro.svg)](https://npmjs.com/package/layerpro)
+[![Downloads](https://img.shields.io/npm/dm/layerpro.svg)](https://npmjs.com/package/layerpro)
+[![License](https://img.shields.io/npm/l/layerpro.svg)](https://github.com/passariello/layerpro/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+<!-- [![Test Status](https://img.shields.io/github/actions/workflow/status/passariello/layerpro/test.yml)](https://github.com/passariello/layerpro/actions) -->
 
-## About
+<!-- [![GitBook Documentation](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/layerpro) -->
+[![Patreon](https://img.shields.io/badge/Support-Patreon-orange.svg)](https://www.patreon.com/passariello)
 
-LayerPro offers a completely new way to customize web modals in your application. With LayerPro, you can create custom alerts, prompts, confirmations, and messages, effectively replacing the default browser modals.
+</div>
 
-## Live demo
+---
+
+## What is LayerPro?
 
-[https://tests.a51.dev/](https://tests.a51.dev/)
+LayerPro is a powerful, lightweight modal and dialog library for modern web applications. It provides a seamless way to create custom alerts, confirmations, prompts, and messages that completely replace the default browser modals.
 
-You can view an HTML version demonstrating how dpHelper and LayerPro work together. These tools can be used with HTML, React, Vue, or any other frontend framework/library.
+Built with TypeScript and designed to work with any frontend framework (React, Vue, Vanilla JS, or plain HTML), LayerPro brings a premium user experience to your web interactions.
 
 ---
 
-## Install for react + webpack projects
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| **🪟 Multiple Modal Types** | Alert, Confirm, Prompt, Message - all customizable |
+| **🎨 Fully Customizable** | Control appearance, behavior, animations |
+| **📍 Dockable Windows** | Minimize modals to a dock bar |
+| **🖱️ Draggable & Resizable** | Users can move and resize modals |
+| **⚡ Smooth Animations** | Built-in fade in/out transitions |
+| **🔒 Security First** | XSS protection with HTML sanitization |
+| **🧠 Memory Safe** | Proper cleanup of React roots and event listeners |
+| **🌐 Universal** | Works with React, Vue, Angular, Vanilla JS |
+| **📱 Responsive** | Adapts to any screen size |
+| **🎯 TypeScript** | Full type definitions included |
 
-```js
-npm i layerpro --save-dev
-```
+---
 
-or update:
+## 📦 Installation
 
-```js
-npm i layerpro@latest --save-dev
+### For React / Vue / Webpack Projects
+
+```bash
+npm install layerpro --save-dev
+# or
+npm install layerpro@latest --save-dev
 ```
 
-in the index (and only there):
+Then import in your entry file:
 
-```js
+```javascript
+// index.js or index.ts
 import "layerpro";
-```
-
-or
 
-```js
-require("layerpro");
+// That's it! Now you can use alert(), confirm(), prompt(), message() globally
 ```
 
-## Install for ejs or other type of projects (like html)
+### For Plain HTML / EJS Projects
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/layerpro"></script>
@@ -51,156 +69,228 @@ require("layerpro");
 
 ---
 
-## How to use it
+## 🚀 Quick Start
 
-ype layerpro in your console to explore all the available tools you can use globally! You can call these tools from anywhere without needing to import them (just include the import once in your index file).
+### Basic Usage
 
-For example, if you type **alert("hello, world!")**, you can see the result.
-
-You can also use these tools as messages directly from the console.
-
-```js
-alert("Hello world"); // Normal alert
-
-prompt("Your Name"); // Ask for input
+```javascript
+// Simple alert
+alert("Hello, World!");
 
+// Confirmation dialog with callbacks
 confirm(
-  "Hello world",
-  ()=>console.log("hello"), // callback for YES / OK
-  ()=>console.log("bye") // callback for NO / CANCEL (you can use null if you don't want CB)
+  "Are you sure?",
+  () => console.log("User clicked YES"),
+  () => console.log("User clicked NO")
 );
 
-message(
-  "Hello world",
-  ()=>console.log("This happen after OK") // callback for YES / OK)
-);
-```
+// Input prompt
+prompt("What's your name?", (value) => {
+  console.log("User entered:", value);
+});
 
-Example:
+// Notification message
+message("Operation completed successfully!");
+```
 
-```js
-import 'layerpro'
+### Advanced Popup
+
+```javascript
+layerpro.popup.open({
+  id: 'myModal',
+  name: 'My Custom Modal',
+  body: '<p>Your custom HTML content here</p>',
+  icon: '&#9888;', // Warning icon HTML entity
+
+  // Dimensions
+  width: 450,
+  height: 350,
+  minWidth: 300,
+  minHeight: 200,
+
+  // Position
+  top: '20%',
+  left: '50%',
+
+  // Features
+  movable: true,
+  resizable: true,
+  maximize: true,
+  iconize: true,
+  dockable: true,
+  close: true,
+
+  // Animation
+  fadeIn: 300,
+  fadeOut: 300,
+
+  // Custom buttons
+  buttons: {
+    confirm: {
+      text: "Accept",
+      cb: () => handleAccept()
+    },
+    cancel: {
+      text: "Cancel",
+      cb: () => handleCancel()
+    }
+  }
+});
+```
 
-// EXAMPLE WITH ALL OPTIONS
-function App() {
+### React Integration
 
-  layerpro.popup.open(
-    {
-      id: 'exampleModal',
-      body: 'Example',
-      name: 'example',
-      icon: '&#9888;',
+```jsx
+import 'layerpro';
+import React from 'react';
 
+function App() {
+  const handleClick = () => {
+    layerpro.popup.open({
+      id: 'react-modal',
+      name: 'React Modal',
+      body: <MyReactComponent />,
+      width: 500,
+      height: 400,
       buttons: {
         confirm: {
-          text: "accept",
-          cb: (e) => message("confirmed")
-        },
-        cancel: {
-          text: "cancel"
+          text: "Save",
+          cb: () => console.log("Saved!")
         }
-      },
-
-      width: 400,
-      height: 300,
-      maxWidth: 500,
-      maxHeight: 350,
-      minWidth: 200,
-      minHeight: 150,
-      top: '10%',
-      left: '10%',
-      right: 'auto',
-      bottom: 'auto',
-
-      fadeIn: 500,
-      fadeOut: 500,
-      timer: 0,
-
-      iconize: true,
-      maximize: true,
-      close: true,
-      isMaximize: false,
-      dockable: false,
-      raised: true,
-      movable: true,
-      resizable: false,
-      store: false
-    }
-  )
-}
-
-export default App
+      }
+    });
+  };
 
+  return (
+    <button onClick={handleClick}>Open Modal</button>
+  );
+}
 ```
 
-Example with a React component:
+---
 
-```js
+## 🎯 API Reference
 
-// Example using React Component
+### Global Functions
 
-import React from "react"
-import 'layerpro'
+| Function | Description |
+|----------|-------------|
+| `alert(text)` | Display a simple alert dialog |
+| `confirm(text, yesCallback, noCallback)` | Display confirmation with callbacks |
+| `prompt(text, callback)` | Display input prompt with callback |
+| `message(text, callback)` | Display notification message |
 
-export default () => {
+### Popup Methods
 
-  // Custom Component6
-  const TestApp = () => {
-    return (
-      <div>
-        Hello
-        <label>
-          Alert: <input type="button" value="Alert" onClick={() => alert("Hello")} />
-        </label>
-      </div>
-    )
-  }
+| Method | Description |
+|--------|-------------|
+| `layerpro.popup.open(props)` | Open a new modal |
+| `layerpro.popup.close(id)` | Close a modal |
+| `layerpro.popup.center(id)` | Center modal on screen |
+| `layerpro.popup.maximize(id)` | Maximize modal |
+| `layerpro.popup.iconize(id)` | Minimize to dock |
+| `layerpro.popup.movable(id)` | Enable drag functionality |
+| `layerpro.popup.resizable(id)` | Enable resize functionality |
+| `layerpro.popup.dockable(id)` | Enable dock functionality |
+| `layerpro.popup.zIndex()` | Get next z-index value |
 
-  // Run into layerpro
-  layerpro.popup.open(
-    {
-      id: 'exampleModal',
-      body: TestApp(),
-      buttons: {
-        confirm: {
-          text: "accept",
-          cb: () => {
-            message("confirmed")
-          }
-        },
-        cancel: {
-          text: "cancel",
-          cb: () => {
-            alert("cancelled")
-          }
-        }
-      },
-      width: 350,
-      height: 300,
-      name: 'example',
-      icon: '&#9888;',
-      iconize: true,
-      maximize: true,
-      close: true,
-      isMaximize: false,
-      dockable: false,
-      raised: true,
-      movable: true,
-      resizable: false,
-      store: false,
-      top: '10%',
-      left: '10%',
-      right: 'auto',
-      bottom: 'auto',
-      minWidth: 200,
-      minHeight: 150,
-      fadeIn: 500,
-      fadeOut: 500,
-      timer: 0
-    }
-  )
+---
 
+## ⚙️ Configuration Options
+
+**Note on `body` parameter:**
+The `body` property supports multiple content types:
+- **Plain text**: `body: "Hello World"`
+- **HTML string**: `body: "<p>Your HTML here</p>"`
+- **React element** (React environment): `body: <MyComponent />`
+
+> ⚠️ **Important**: When using React, always pass components as elements (`<MyComponent />`), not as function calls (`MyComponent()`). Passing a function will show an error message.
+
+```typescript
+interface GenLayerProps {
+  id: string;                    // Unique identifier
+  body?: any;                    // Modal content (HTML string or React component)
+  name?: string;                 // Modal title
+  icon?: string;                 // Icon HTML entity
+
+  // Dimensions
+  width?: number | string;       // Width in px or %
+  height?: number | string;      // Height in px or %
+  minWidth?: number;             // Minimum width
+  minHeight?: number;            // Minimum height
+  maxWidth?: number;             // Maximum width
+  maxHeight?: number;            // Maximum height
+
+  // Position
+  top?: number | string;         // Top position
+  left?: number | string;        // Left position
+  right?: number | string;       // Right position
+  bottom?: number | string;      // Bottom position
+
+  // Animation
+  fadeIn?: number;               // Fade in duration (ms)
+  fadeOut?: number;              // Fade out duration (ms)
+  timer?: number;                // Auto-close timer
+
+  // Features
+  maximize?: boolean;            // Show maximize button
+  isMaximize?: boolean;          // Start maximized
+  dockable?: boolean;            // Enable dock feature
+  movable?: boolean;            // Enable drag
+  resizable?: boolean;          // Enable resize
+  close?: boolean;              // Show close button
+  raised?: boolean;             // Show raised overlay
+  iconize?: boolean;            // Show minimize button
+
+  // Behavior
+  source?: string;               // Content source URL
+  store?: boolean;               // Store state
+
+  // Custom Buttons
+  buttons?: {
+    confirm?: { text: string; cb?: () => void };
+    cancel?: { text: string; cb?: () => void };
+  };
 }
 ```
 
-copyright (c) 2019 - 2025 by Dario Passariello
+---
+
+## 🌍 Browser Support
+
+| Browser | Version |
+|---------|---------|
+| Chrome | 80+ |
+| Firefox | 75+ |
+| Safari | 13+ |
+| Edge | 80+ |
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE.md](LICENSE.md) for details.
+
+---
+
+## 👤 Author
+
+**Dario Passariello**
+
+- GitHub: [@passariello](https://github.com/passariello)
+- Email: dariopassariello@gmail.com
+- Website: https://dario.passariello.ca
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+---
+
+<div align="center">
+
+Made with ❤️ by [Dario Passariello](https://dario.passariello.ca) with a lot of caffe' espresso!
+
+</div>