layerpro 3.0.1 → 3.1.1

package/README.md

@@ -66,7 +66,17 @@ Import LayerPro once in your app entry point:
 import "layerpro";
 ```
 
-That's it. Now you have `alert()`, `confirm()`, `prompt()`, and `message()` globally.
+That's it. Now you have `alert()`, `confirm()`, `prompt()`, `message()`, and `popup()` globally available.
+
+The `popup` alias is a shorthand for `layerpro.popup`:
+
+```javascript
+import "layerpro";
+
+// Both work identically:
+layerpro.popup.open({ id: 'myPopup', body: 'Hello World' });
+popup.open({ id: 'myPopup', body: 'Hello World' });
+```
 
 ---
 
@@ -90,8 +100,23 @@ message("Operation complete!");
 
 ### Custom Popups
 
+You can use either `layerpro.popup.open(...)` or the shorthand `popup.open(...)`:
+
 ```javascript
-layerpro.popup.open({
+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: () => {} }
+  }
+});
+
+// Or using the global alias:
+popup.open({
   id: 'myModal',
   name: 'My Modal',
   body: '<p>Your content here</p>',
@@ -109,7 +134,7 @@ layerpro.popup.open({
 In a React environment, you can pass React components directly:
 
 ```jsx
-layerpro.popup.open({
+popup.open({
   id: 'reactModal',
   name: 'React Modal',
   body: <MyComponent />,   // React element
@@ -136,12 +161,13 @@ The `body` property accepts different content types:
 
 ```typescript
 {
-  id: string,           // Unique ID
+  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 (HTML entity)
+  icon: string,         // Icon glyph — HTML entity (e.g. "&#9888;") or an HTML
+                         //     string (e.g. '<i class="fa fa-star"></i>')
 
-  // Dimensions
+  // Dimensions (defaults: width 340, height 220; minWidth 340, minHeight 220)
   width: number,
   height: number,
   minWidth: number,
@@ -149,25 +175,32 @@ The `body` property accepts different content types:
   maxWidth: number,
   maxHeight: number,
 
-  // Position
+  // Remote content (same-origin only for security)
+  source: string,         // URL to fetch HTML content from (same-origin enforced)
+
+  // 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)
 
   // Animation
-  fadeIn: number,
-  fadeOut: number,
-  timer: number,
+  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,
-  resizable: boolean,
-  maximize: boolean,
-  iconize: boolean,
-  dockable: boolean,
-  close: boolean,
-  raised: boolean,
+  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
 
   // Buttons
   buttons: {
@@ -177,19 +210,99 @@ 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.
+
+> **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:
+
+```javascript
+import "layerpro";
+
+alert("Hello World!");              // LayerPro alert
+confirm("Sure?", yes => {...});     // LayerPro confirm (callback, not a boolean return!)
+prompt("Name?", name => {...});     // LayerPro prompt (callback, not a string return!)
+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:
+>
+> ```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.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` |
+
+---
+
+## 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:
+
+```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:
+
+| Variable | Applies to |
+|----------|-----------|
+| `--bar-background` | title bar |
+| `--bar-selected-background` | active/selected title bar |
+| `--bar-color` | title bar text |
+| `--window-background` | popup surface |
+| `--window-shadow` | popup shadow |
+| `--window-border-radius` | popup border radius |
+| `--internal-background` | body wrapper |
+| `--body-color` | body text color |
+| `--raised-background` | modal overlay |
+| `--popup-z-index` | base z-index for the stack |
+
 ---
 
 ## Methods
 
 | Method | Description |
 |--------|-------------|
-| `layerpro.popup.open(props)` | Open a modal |
-| `layerpro.popup.close(id)` | Close a modal |
-| `layerpro.popup.center(id)` | Center modal |
-| `layerpro.popup.maximize(id)` | Maximize modal |
-| `layerpro.popup.iconize(id)` | Minimize to dock |
-| `layerpro.popup.movable(id)` | Enable drag |
-| `layerpro.popup.resizable(id)` | Enable resize |
+| `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 |
 
 ---
 
@@ -199,6 +312,20 @@ 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 `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,