layerpro 3.2.0 → 3.4.0

package/README.md

@@ -1,4 +1,4 @@
-# [LayerPro](https://npmjs.com/package/layerpro)
+# LayerPro
 
 ![layerpro](https://raw.githubusercontent.com/passariello/container/be0611e9bead336dcec32d522d103e7e3661f502/layerpro/assets/logos/logo.svg)
 
@@ -7,42 +7,50 @@
 
 ![Snyk](https://img.shields.io/badge/Snyk-gray?logo=Snyk)
 ![Socket](https://img.shields.io/badge/Socket-gray?logo=Socket)
-
 ![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
 ![Browser](https://img.shields.io/badge/Browser-gray?logo=google-chrome)
 ![Deno](https://img.shields.io/badge/Deno-gray?logo=deno)
 ![tsup](https://img.shields.io/badge/tsup-gray?logo=esbuild)
-
 ![React](https://img.shields.io/badge/React-gray?logo=React)
 ![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
 ![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
-
 ![Vitest](https://img.shields.io/badge/Vitest-gray?logo=vitest)
 ![OXlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
 ![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
 
----
-
-## What is LayerPro?
-
-LayerPro replaces the boring browser `alert()`, `confirm()`, and `prompt()` with beautiful, customizable modals that work everywhere.
-
-No more ugly popup boxes. No more blocking the main thread. Just clean, modern modals that your users will love.
+LayerPro replaces the browser's native `alert()`, `confirm()`, and `prompt()` with beautiful, fully customizable modals that work everywhere - no more blocking the main thread, no more default browser styling.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Basic Modals](#basic-modals)
+  - [Custom Popups](#custom-popups)
+  - [React Components](#react-components)
+  - [The `body` Parameter](#the-body-parameter)
+- [Options](#options)
+- [Global Overrides](#global-overrides)
+- [Methods](#methods)
+- [Styling & z-index](#styling--z-index)
+- [Security](#security)
+- [Browser Support](#browser-support)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
 ## Features
 
-- **Zero runtime dependencies**: no jQuery — pure vanilla DOM helpers; `react`/`react-dom` are peer dependencies (only loaded when React bodies are used, powered by [`reattach`](https://npmjs.com/package/reattach))
-- **Multiple modal types**: alert, confirm, prompt, message
-- **Fully customizable**: appearance, behavior, and content
-- **Dockable windows (taskbar style)**: click a dock icon to restore, focus, or minimize — just like an OS taskbar
-- **Draggable & Resizable**: instant, with no transition lag while resizing
-- **Maximize is pure CSS**: uses `position: fixed` + insets, so it follows the viewport with no JS resize listeners
-- **Fade in/out** transitions for open/close
-- **TypeScript support**: full type definitions
-
----
+- **Zero runtime dependencies** - no jQuery, pure vanilla DOM helpers; `react`/`react-dom` are peer dependencies, only loaded when React bodies are used, powered by [`reattach`](https://npmjs.com/package/reattach)
+- **Multiple modal types** - alert, confirm, prompt, message
+- **Fully customizable** - appearance, behavior, and content
+- **Dockable windows** (taskbar-style) - click a dock icon to restore, focus, or minimize, just like an OS taskbar
+- **Draggable & resizable** - instant, with no transition lag while resizing
+- **CSS-only maximize** - uses `position: fixed` + insets, so it follows the viewport with no JS resize listeners
+- **Fade in/out transitions** for open/close
+- **Full TypeScript support**
 
 ## Installation
 
@@ -56,17 +64,15 @@ Or use directly in HTML:
 <script src="https://cdn.jsdelivr.net/npm/layerpro"></script>
 ```
 
----
-
 ## Quick Start
 
-Import LayerPro once in your app entry point:
+Import LayerPro once, in your app's entry point:
 
 ```javascript
 import "layerpro";
 ```
 
-That's it. Now you have `alert()`, `confirm()`, `prompt()`, `message()`, and `popup()` globally available.
+That's it - `alert()`, `confirm()`, `prompt()`, `message()`, and `popup()` are now available globally.
 
 The `popup` alias is a shorthand for `layerpro.popup`:
 
@@ -78,8 +84,6 @@ layerpro.popup.open({ id: 'myPopup', body: 'Hello World' });
 popup.open({ id: 'myPopup', body: 'Hello World' });
 ```
 
----
-
 ## Usage
 
 ### Basic Modals
@@ -100,8 +104,6 @@ message("Operation complete!");
 
 ### Custom Popups
 
-You can use either `layerpro.popup.open(...)` or the shorthand `popup.open(...)`:
-
 ```javascript
 popup.open({
   id: 'myModal',
@@ -114,33 +116,17 @@ popup.open({
     cancel: { text: "Cancel", cb: () => {} }
   }
 });
-
-// Or using the global alias:
-popup.open({
-  id: 'myModal',
-  name: 'My Modal',
-  body: '<p>Your content here</p>',
-  width: 450,
-  height: 350,
-  buttons: {
-    confirm: { text: "OK", cb: () => {} },
-    cancel: { text: "Cancel", cb: () => {} }
-  }
-});
 ```
 
 ### React Components
 
-LayerPro's React adapter is powered by [`reattach`](https://npmjs.com/package/reattach) — a
-zero-dependency library for mounting React components anywhere in the DOM. reattach handles
-root creation, automatic root reuse on duplicate-id reopen, **Context Bridging** across
-detached roots, and **Auto-healing DOM** recovery — all without you lifting a finger.
+LayerPro's React adapter is powered by [`reattach`](https://npmjs.com/package/reattach), a zero-dependency library for mounting React components anywhere in the DOM. It handles root creation, automatic root reuse on duplicate-id reopen, **Context Bridging** across detached roots, and **auto-healing DOM** recovery - all without extra setup.
 
 ```jsx
 popup.open({
   id: 'reactModal',
   name: 'React Modal',
-  body: <MyComponent />,   // React element
+  body: <MyComponent />,
   width: 500,
   height: 400
 });
@@ -166,34 +152,29 @@ function App() {
 popup.open({
   id: 'contextual',
   body: <ThemedWidget />,
-  inheritContext: true,   // ContextBridge: ThèmeContext is bridged
-  resilient: true,        // Auto-heals if the container is replaced
+  inheritContext: true,
+  resilient: true,
 });
 ```
 
 ### The `body` Parameter
 
-The `body` property accepts different content types:
-
 | Type | Example |
 |------|---------|
 | Plain text | `body: "Hello"` |
 | HTML string | `body: "<p>Hello</p>"` |
 | React element | `body: <Component />` |
 
-> **Note**: In React, always use elements (`<Component />`), not function calls (`Component()`).
-
----
+> **Note**: in React, always use elements (`<Component />`), not function calls (`Component()`).
 
 ## Options
 
 ```typescript
 {
-  id: string,           // Unique ID (auto-generated as popup_1, popup_2, ... if omitted)
-  body: any,            // Content (text, HTML, or React)
-  name: string,         // Modal title
-  icon: string,         // Icon glyph — HTML entity (e.g. "&#9888;") or an HTML
-                         //     string (e.g. '<i class="fa fa-star"></i>')
+  id: string,             // Unique ID (auto-generated as popup_1, popup_2, ... if omitted)
+  body: any,              // Content (text, HTML, or React)
+  name: string,           // Modal title
+  icon: string,           // Icon glyph - HTML entity (e.g. "&#9888;") or HTML string
 
   // Dimensions (defaults: width 340, height 220; minWidth 340, minHeight 220)
   width: number,
@@ -203,36 +184,34 @@ The `body` property accepts different content types:
   maxWidth: number,
   maxHeight: number,
 
-  // Remote content (same-origin only for security)
-  source: string,         // URL to fetch HTML content from (same-origin enforced)
+  // Remote content (same-origin only, enforced)
+  source: string,
 
   // React adapter (via reattach)
-  inheritContext: boolean, // reattach Context Bridge — replay host React Context into the popup root
-  resilient: boolean,      // reattach Auto-healing DOM — MutationObserver recovery from external DOM mutations
+  inheritContext: boolean,
+  resilient: boolean,
 
   // Position (numbers are px; strings applied as-is, e.g. "10%")
   top: number | string,
   left: number | string,
   right: number | string,
   bottom: number | string,
-  center: boolean,      // Center the popup in the viewport (adds a small
-                         //     cascade offset per open window so stacks don't overlap)
+  center: boolean,        // Center the popup (adds a small cascade offset per open window)
 
   // Animation
-  fadeIn: number,       // open fade duration (ms, default 100)
-  fadeOut: number,      // close fade duration (ms, default 100)
-  timer: number,        // auto-close after N ms
+  fadeIn: number,         // open fade duration (ms, default 100)
+  fadeOut: number,        // close fade duration (ms, default 100)
+  timer: number,          // auto-close after N ms
 
   // Features
-  movable: boolean,     // draggable by the title bar
-  resizable: boolean,   // resize handles
-  maximize: boolean,    // double-click title bar to maximize
-  iconize: boolean,     // allow minimize to dock
-  dockable: boolean,    // show an icon in the dock bar
-  close: boolean,       // show the close button
-  raised: boolean,      // alias: modal — show a full-screen overlay that blocks
-                         //     pointer events to the page underneath
-  modal: boolean,       // alias of raised
+  movable: boolean,
+  resizable: boolean,
+  maximize: boolean,      // double-click title bar to maximize
+  iconize: boolean,       // allow minimize to dock
+  dockable: boolean,      // show an icon in the dock bar
+  close: boolean,         // show the close button
+  raised: boolean,        // alias: modal - full-screen overlay that blocks pointer events beneath
+  modal: boolean,         // alias of raised
 
   // Buttons
   buttons: {
@@ -242,19 +221,13 @@ The `body` property accepts different content types:
 }
 ```
 
-> **`raised` / `modal`** injects a full-viewport overlay (`popup_raised_<id>`) that
-> intercepts every pointer event — the page underneath becomes unclickable until the
-> popup closes. This is modal behavior; both names are accepted.
+> **`raised` / `modal`** injects a full-viewport overlay (`popup_raised_<id>`) that intercepts every pointer event - the page underneath becomes unclickable until the popup closes. Both names are accepted.
 
-> **Duplicate id** — opening a popup whose `id` already exists brings that window to
-> the front and refreshes its `body`/`buttons` instead of doing nothing.
-
----
+> **Duplicate id** - opening a popup whose `id` already exists brings that window to the front and refreshes its `body`/`buttons` instead of doing nothing.
 
 ## Global Overrides
 
-Importing LayerPro replaces the native `alert`, `confirm`, and `prompt` globals with
-callback-based versions, and adds a `message` global:
+Importing LayerPro replaces the native `alert`, `confirm`, and `prompt` globals with callback-based versions, and adds a `message` global:
 
 ```javascript
 import "layerpro";
@@ -265,49 +238,37 @@ prompt("Name?", name => {...});     // LayerPro prompt (callback, not a string r
 message("Done!");                   // LayerPro message
 ```
 
-> **⚠️ Important:** the overridden `confirm()` no longer returns a `boolean` and
-> `prompt()` no longer returns a `string`. They are callback-based and return
-> `undefined`. Any third-party code that does `if (confirm("..."))` will silently
-> fall into the falsy branch. If your codebase depends on the native synchronous
-> return values, call **`layerpro.noGlobals()`** right after importing LayerPro to
-> restore the originals:
+> **⚠️ Important:** the overridden `confirm()` no longer returns a `boolean`, and `prompt()` no longer returns a `string` - they are callback-based and return `undefined`. Any third-party code that does `if (confirm("..."))` will silently fall into the falsy branch. If your codebase depends on native synchronous return values, call **`layerpro.noGlobals()`** right after importing LayerPro to restore the originals:
 >
 > ```javascript
 > import "layerpro";
 > layerpro.noGlobals();   // restores native alert/confirm/prompt, drops `message`
 > ```
 
----
-
 ## Methods
 
 | Method | Description |
 |--------|-------------|
-| `popup.open(props)` | Open a modal; returns the props. Re-opens a same-id window to front + refreshes body. |
+| `popup.open(props)` | Open a modal; returns the props. Re-opens a same-id window to front and refreshes its body. |
 | `popup.close(id)` | Close (and unmount) a modal. |
-| `popup.center(id, offset?)` | Center a modal in the viewport; optional pixel offset |
-| `popup.maximize(props)` | Toggle maximize (pure CSS) |
-| `popup.iconize(id)` | Toggle minimize to the dock |
-| `popup.index(id)` | Bring a modal to the front (select) |
-| `popup.zIndex()` | Get the next z-index counter value |
-| `popup.movable(props)` | Enable dragging |
-| `popup.resizable(props)` | Enable resizing |
-| `layerpro.noGlobals()` | Restore native `alert`/`confirm`/`prompt`; remove `message` |
-
----
+| `popup.center(id, offset?)` | Center a modal in the viewport; optional pixel offset. |
+| `popup.maximize(props)` | Toggle maximize (pure CSS). |
+| `popup.iconize(id)` | Toggle minimize to the dock. |
+| `popup.index(id)` | Bring a modal to the front (select). |
+| `popup.zIndex()` | Get the next z-index counter value. |
+| `popup.movable(props)` | Enable dragging. |
+| `popup.resizable(props)` | Enable resizing. |
+| `layerpro.noGlobals()` | Restore native `alert`/`confirm`/`prompt`; remove `message`. |
 
 ## Styling & z-index
 
-Popups live in a `#popup` container whose base z-index comes from the
-`--popup-z-index` CSS variable (default `1000`). Apps with their own stacking
-contexts can override it to shift the whole stack:
+Popups live in a `#popup` container whose base z-index comes from the `--popup-z-index` CSS variable (default `1000`). Apps with their own stacking contexts can override it to shift the whole stack:
 
 ```scss
 :root { --popup-z-index: 100000; }
 ```
 
-The title bar, window surface, internal area, and body all read from CSS custom
-properties, so theming needs no `!important` or `[class^=popup_…]` selectors:
+The title bar, window surface, internal area, and body all read from CSS custom properties, so theming needs no `!important` or fragile class selectors:
 
 | Variable | Applies to |
 |----------|-----------|
@@ -322,58 +283,25 @@ properties, so theming needs no `!important` or `[class^=popup_…]` selectors:
 | `--raised-background` | modal overlay |
 | `--popup-z-index` | base z-index for the stack |
 
----
-
-## Methods
-
-| Method | Description |
-|--------|-------------|
-| `popup.open(props)` | Open a modal |
-| `popup.close(id)` | Close a modal |
-| `popup.center(id)` | Center modal |
-| `popup.maximize(id)` | Maximize modal |
-| `popup.iconize(id)` | Minimize to dock |
-| `popup.movable(id)` | Enable drag |
-| `popup.resizable(id)` | Enable resize |
+## Security
 
----
+- **Same-origin fetch guard** - the `source` prop only accepts same-origin URLs; cross-origin requests are rejected before any network call is made, preventing SSRF and data exfiltration.
+- **HTML escaping** - all user-provided text content (button labels, body content, titles) is automatically escaped via `escapeHtml()` to prevent XSS.
+- **CSP-friendly** - no inline scripts or `eval()` are used. React components are rendered via `reattach.mount()` (backed by `createRoot()`).
+- **Opt-out of global overrides** - call `layerpro.noGlobals()` after import to restore native `alert`, `confirm`, `prompt`, and remove the `message` global if your codebase depends on synchronous return values.
 
 ## Browser Support
 
 Chrome 80+ • Firefox 75+ • Safari 13+ • Edge 80+
 
----
-
-## Security
-
-LayerPro includes several security measures:
-
-- **Same-origin fetch guard**: The `source` prop only accepts same-origin URLs. Cross-origin requests are rejected before any network call is made, preventing SSRF and data exfiltration.
-
-- **HTML escaping**: All user-provided text content (button labels, body content, titles) is automatically escaped via `escapeHtml()` to prevent XSS. HTML entities like `<`, `>`, `&`, `"` are converted to their safe equivalents.
-
-- **Content Security Policy friendly**: No inline scripts or `eval()` are used. React components are rendered via `reattach.mount()` (backed by `createRoot()`) with proper sanitization.
-
-- **No global pollution option**: Call `layerpro.noGlobals()` after import to restore native `alert`, `confirm`, `prompt` and remove the `message` global if your codebase depends on synchronous return values.
-
----
-
 ## Contributing
 
-LayerPro is **open source** and free for everyone. The current source is private,
-but **anyone is welcome to join**. If you'd like to contribute, propose changes,
-or just talk about the project, get in touch:
-
-- **Dario Passariello** — https://dario.passariello.ca/ — dariopassariello@gmail.com
+LayerPro's source is currently private, but contributions and discussion are welcome. Get in touch:
 
-Participation is voluntary and free — everyone is free to take part.
-
----
+- **Dario Passariello** - https://dario.passariello.ca/ - dariopassariello@gmail.com
 
 ## License
 
 MIT License
 
-## Credits
-
-Copyrigth (c) [Dario Passariello](https://dario.passariello.ca/)
+Copyright (c) [Dario Passariello](https://dario.passariello.ca/)