layerpro 3.4.0 → 4.0.1

package/README.md

@@ -18,7 +18,11 @@
 ![OXlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
 ![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
 
-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.
+LayerPro is a browser window system: it generates **OS-style windows** - draggable, resizable, maximizable, dockable - that can host any content, including **React components**.
+
+It also 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.
+
+LayerPro is **not only** a replacement for `alert`/`prompt`/`confirm`: the same window engine is used to build rich, interactive windows on top of your app.
 
 ## Table of Contents
 
@@ -28,15 +32,19 @@ LayerPro replaces the browser's native `alert()`, `confirm()`, and `prompt()` wi
 - [Usage](#usage)
   - [Basic Modals](#basic-modals)
   - [Custom Popups](#custom-popups)
+  - [OS-style Windows](#os-style-windows)
   - [React Components](#react-components)
   - [The `body` Parameter](#the-body-parameter)
 - [Options](#options)
 - [Global Overrides](#global-overrides)
 - [Methods](#methods)
 - [Styling & z-index](#styling--z-index)
+- [Overriding the CSS](#overriding-the-css)
+  - [CSS custom properties](#1-css-custom-properties-recommended)
+  - [Target the generated classes](#2-target-the-generated-classes)
+  - [Cascade layers](#3-cascade-layers-full-control)
+- [Dock](#dock)
 - [Security](#security)
-- [Browser Support](#browser-support)
-- [Contributing](#contributing)
 - [License](#license)
 
 ---
@@ -44,7 +52,9 @@ LayerPro replaces the browser's native `alert()`, `confirm()`, and `prompt()` wi
 ## 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
+- **OS-style window engine** - not just modals: every popup is a real window with a title bar, drag handle, resize handles, maximize/restore, minimize-to-dock, focus stacking, and a z-order you control
+- **Hosts any content** - plain text, HTML strings, or **full React components** (with Context bridging and DOM auto-healing), rendered inside the window body
+- **Multiple modal types** - alert, confirm, prompt, message - built on top of the same window engine, so they inherit the same styling, dock, and accessibility features
 - **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
@@ -72,7 +82,7 @@ Import LayerPro once, in your app's entry point:
 import "layerpro";
 ```
 
-That's it - `alert()`, `confirm()`, `prompt()`, `message()`, and `popup()` are now available globally.
+That's it - `layerpro.popup()`, `layerpro.alert()`, `layerpro.confirm()`, `layerpro.prompt()`, `layerpro.message()` and `layerpro.version()` are now available. Import `layerpro/global` instead if you also want the browser's own `alert`/`confirm`/`prompt` overridden (see [Global Overrides](#global-overrides-opt-in-in-40)).
 
 The `popup` alias is a shorthand for `layerpro.popup`:
 
@@ -89,19 +99,15 @@ popup.open({ id: 'myPopup', body: 'Hello World' });
 ### Basic Modals
 
 ```javascript
-alert("Hello World!");
+layerpro.alert("Hello World!");                       // Promise<void>
+layerpro.message("Operation complete!");              // Promise<void>
 
-confirm("Are you sure?", () => {
-  console.debug("User clicked YES");
-});
-
-prompt("What's your name?", (name) => {
-  console.debug("User entered:", name);
-});
-
-message("Operation complete!");
+const confirmed = await layerpro.confirm("Are you sure?");   // Promise<boolean>
+const name = await layerpro.prompt("What's your name?");     // Promise<string>
 ```
 
+> **Note:** with the default `import "layerpro"` entry the browser's own `alert`/`confirm`/`prompt` are **not** replaced. Use `import "layerpro/global"` to opt in to the global overrides, or call the `layerpro.*` methods directly as shown above.
+
 ### Custom Popups
 
 ```javascript
@@ -118,6 +124,48 @@ popup.open({
 });
 ```
 
+### OS-style Windows
+
+A popup is not limited to a modal dialog. Turn on `movable`, `resizable`, `maximize`, `iconize` and `dockable` and it becomes a real OS-style window: draggable by its title bar, resizable from the edges, maximizable, minimizable into the dock, and stackable with the other windows on the page.
+
+```javascript
+popup.open({
+  id: 'dashboard',
+  name: 'Dashboard',
+  icon: '&#128202;',
+  body: '<h2>Live metrics</h2><p>Anything you want inside.</p>',
+  width: 640,
+  height: 420,
+  movable: true,
+  resizable: true,
+  maximize: true,
+  iconize: true,
+  dockable: true,
+  close: true
+});
+```
+
+Combined with a React component, this becomes a real application window - a dashboard, a settings panel, a file browser - rendered inside the browser page with native-looking chrome:
+
+```jsx
+popup.open({
+  id: 'settingsWindow',
+  name: 'Settings',
+  icon: '&#9881;',
+  body: <SettingsPanel />,
+  width: 720,
+  height: 480,
+  movable: true,
+  resizable: true,
+  maximize: true,
+  iconize: true,
+  dockable: true,
+  close: true
+});
+```
+
+> **Tip:** `modal: true` is what turns a window into a blocking dialog. Leave it off for windows the user should be able to move around while working on the page.
+
 ### 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. 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.
@@ -184,12 +232,13 @@ popup.open({
   maxWidth: number,
   maxHeight: number,
 
-  // Remote content (same-origin only, enforced)
-  source: string,
+   // Remote content (same-origin only, enforced). Rendered as raw HTML;
+   // sanitize server-side if the endpoint is not fully trusted.
+   source: string,
 
-  // React adapter (via reattach)
-  inheritContext: boolean,
-  resilient: boolean,
+   // React adapter (via reattach)
+   inheritContext: boolean,
+   resilient: boolean,
 
   // Position (numbers are px; strings applied as-is, e.g. "10%")
   top: number | string,
@@ -210,8 +259,7 @@ popup.open({
   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
+   modal: boolean,          // full-screen overlay that blocks pointer events beneath
 
   // Buttons
   buttons: {
@@ -221,44 +269,60 @@ popup.open({
 }
 ```
 
-> **`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.
+> **`modal`** injects a full-viewport overlay (`popup_modal_<id>`) that intercepts every pointer event - the page underneath becomes unclickable until the popup closes. Use `modal: true` for alert/confirm/prompt/message pop ups.
 
 > **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
+## Global Overrides (Opt-in in 4.0)
 
-Importing LayerPro replaces the native `alert`, `confirm`, and `prompt` globals with callback-based versions, and adds a `message` global:
+In 4.0, `import "layerpro"` no longer overrides the native `alert`, `confirm`,
+and `prompt` globals. The library exposes its own methods on `window.layerpro`
+and provides Promise-based alternatives. To override the browser globals, use
+the **explicit entrypoint**:
 
 ```javascript
+// Default entry - library installed, globals NOT overridden
 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
+layerpro.alert("Hello World!");              // Promise<void>
+const confirmed = await layerpro.confirm("Sure?");   // Promise<boolean>
+const name = await layerpro.prompt("Name?");          // Promise<string>
+layerpro.message("Done!");                            // Promise<void>
+```
+
+### Override browser globals (opt-in)
+
+If you need `window.alert` / `window.confirm` / `window.prompt` / `window.message`
+replaced with LayerPro's Promise-based versions, import the global entrypoint:
+
+```javascript
+import "layerpro/global";  // installs Promise-based overrides on window
+
+// These now return Promises instead of native values:
+await alert("Hello World!");              // Promise<void>
+const ok = await confirm("Sure?");        // Promise<boolean>
+const val = await prompt("Name?");        // Promise<string>
 ```
 
-> **⚠️ 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`
-> ```
+> **⚠️ Important:** overridden `confirm()` returns `Promise<boolean>`, not a
+> synchronous `boolean`. Code that does `if (confirm("..."))` must be
+> `await`-ed. Only use `layerpro/global` if you control all call sites.
 
 ## Methods
 
 | Method | Description |
 |--------|-------------|
-| `popup.open(props)` | Open a modal; returns the props. Re-opens a same-id window to front and refreshes its body. |
+| `popup.open(props)` | Open a modal; returns `Promise<GenLayerProps>` - resolves when the popup closes. |
 | `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`. |
+| `layerpro.installGlobals()` | Override `window.alert/confirm/prompt/message` with LayerPro's Promise-based versions. |
+| `layerpro.version()` | Returns the current LayerPro version string (read from `app.json`). |
+| `layerpro.config(opts)` | Runtime config. Currently supports `{ nonce: string }` for CSP; sets `window.__layerproNonce` consumed by the injected `<style>`. Call before importing LayerPro for the nonce to be present at injection. |
 
 ## Styling & z-index
 
@@ -280,25 +344,196 @@ The title bar, window surface, internal area, and body all read from CSS custom
 | `--window-border-radius` | popup border radius |
 | `--internal-background` | body wrapper |
 | `--body-color` | body text color |
-| `--raised-background` | modal overlay |
+ | `--modal-background` | modal overlay |
 | `--popup-z-index` | base z-index for the stack |
 
-## Security
+Additional variables available for buttons, inputs, resize handles, and the dock:
 
-- **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.
+| Variable | Applies to |
+|----------|-----------|
+| `--button-background-color` / `--button-color` | confirm/cancel buttons |
+| `--input-background-color` / `--input-color` | prompt input field |
+| `--inputButton-fontSize` | button/input font size |
+| `--resize-background-color` / `--resize-shadow` | resize handles |
+| `--dock-background-color` / `--dock-height` | taskbar strip |
+| `--dock-sideLeft` / `--dock-sideCenter` / `--dock-sideRight` | dock alignment |
+| `--dock-icon-width` | dock icon width |
+| `--transition-time` | fade/hover transitions |
+| `--border-radius` / `--corner-size` / `--corner-border-radius` | resize handle shape |
+| `--hover-opacity` / `--hover-filter` | hover feedback |
+
+## Overriding the CSS
+
+LayerPro ships its styles **injected at runtime** into a `<style>` tag (no separate CSS import needed). There are three ways to restyle it, from the most recommended to the most surgical.
+
+> **No inline styles.** LayerPro never writes a plain inline style on the elements it renders. Every declaration lives in the stylesheet and is driven by a **class** (the state) or by a **CSS custom property** (the value). That means you can restyle any part of a window with a plain CSS rule - nothing needs `!important` to win over an inline style.
+
+### 1. CSS custom properties (recommended)
+
+Every visual detail is driven by a CSS variable declared on `:root`. Override the variable and every popup updates - no selectors, no `!important`:
+
+```css
+:root {
+  --bar-background: #1f2937;
+  --bar-selected-background: #2563eb;
+  --bar-color: #f9fafb;
+  --window-background: #111827;
+  --window-border-radius: 4px;
+  --internal-background: #0b1220;
+  --body-color: #e5e7eb;
+  --button-background-color: #2563eb;
+  --button-color: #ffffff;
+}
+```
+
+Variables can also be scoped per popup subtree, because each window is rendered inside `#popup`:
 
-## Browser Support
+```css
+#popup .popup_window_myDarkPopup {
+  --window-background: #000;
+  --bar-background: #000;
+}
+```
+
+### 2. Target the generated classes
+
+Every element LayerPro creates carries a **stable class alias** next to its id-suffixed class, so you can target windows, bars, bodies, and buttons without depending on generated ids:
+
+| Element | Stable class | Id-suffixed class |
+|---------|--------------|-------------------|
+| Window surface | `.popup_window` | `.popup_window_<id>` |
+| Title bar | `.popup_bar` | `.popup_bar_<id>` |
+| Drag handle (title) | `.popup_drag` | `.popup_drag_<id>` |
+| Icon slot | `.popup_icon` | `.popup_icon_<id>` |
+| Option buttons | `.popup_option` | `.popup_option_<id>` |
+| Internal area | `.popup_internal` | `.popup_internal_<id>` |
+| Body | `.popup_body` | `.popup_body_<id>` |
+| Modal overlay | `.popup_modal` | `.popup_modal_<id>` |
+| Positioned wrapper | `.popup_overflow` | `.popup_overflow_<id>` |
+| Confirm/cancel row | `.buttons` | - |
+| Selected/focused window | `.zHigh`, `.popup_bar_selected` | - |
+
+```css
+/* square windows, no rounded corners */
+#popup .popup_window {
+  border-radius: 0;
+}
+
+/* restyle the confirm/cancel row */
+#popup .buttons button {
+  border-radius: 6px;
+  background: #2563eb;
+}
+
+/* make the close button red on hover */
+#popup .popup_option .close:hover {
+  background: #dc2626;
+}
+
+/* change the dock strip */
+#popup_dock {
+  background: #111827;
+}
+```
 
-Chrome 80+ • Firefox 75+ • Safari 13+ • Edge 80+
+> **Note:** some internal rules use `!important` (for example the active-window border and the built-in icons). For those, use the cascade layer approach below instead of `!important`.
+
+### State classes
+
+The visual **states** of a window are classes too, so you can restyle them like any other element:
+
+| Class | Applied when | Effect |
+|-------|--------------|--------|
+| `.popup_maximized` | the window is maximized | fills the viewport above the dock |
+| `.popup_iconized` | the window is minimized to the dock | collapsed on the taskbar |
+| `.popup_dimmed` | another window has the focus | pushed to the back (opacity `.5`) |
+| `.popup_content_hidden` | another window has the focus | body content not rendered |
+| `.popup_content_visible` | the window has the focus | body content always rendered |
+| `.lp_hidden` | the element is hidden | `display: none` |
+| `.lp_fade_in` / `.lp_fade_out` | during a fade | opacity transition |
+| `.lp_no_pointer` | while dragging/resizing | `pointer-events: none` |
+| `.lp_no_touch` | on the drag/resize handles | `touch-action: none` |
+| `.lp_no_transition` | while resizing | transitions disabled |
+
+```css
+/* a maximized window with a different look */
+#popup .popup_maximized {
+  inset: 0;
+  bottom: 0;
+}
+
+/* a dimmed window that stays readable */
+#popup .popup_dimmed {
+  opacity: .8;
+}
+```
+
+The geometry of a window (position and size) is carried by the custom properties below, so it can be overridden too:
+
+| Property | Value |
+|----------|-------|
+| `--lp-top` / `--lp-left` | window position |
+| `--lp-right` / `--lp-bottom` | window position (alternative anchors) |
+| `--lp-width` / `--lp-height` | window size |
+| `--lp-min-width` / `--lp-min-height` | minimum size |
+| `--lp-max-width` / `--lp-max-height` | maximum size |
+| `--lp-z-index` | stacking order |
+
+```css
+/* every window opens at a fixed position */
+#popup .popup_overflow {
+  --lp-left: 50%;
+  --lp-top: 100px;
+}
+```
 
-## Contributing
+### 3. Cascade layers (full control)
 
-LayerPro's source is currently private, but contributions and discussion are welcome. Get in touch:
+All LayerPro styles live inside the CSS cascade layer `layerpro`, so a host app can restyle the popups without `!important` or fragile selectors.
 
-- **Dario Passariello** - https://dario.passariello.ca/ - dariopassariello@gmail.com
+```css
+/* host app: plain rules beat every layer */
+#popup { border-radius: 4px; }
+```
+
+Precedence rules:
+
+- **Unlayered host rules always win** over anything inside `layerpro`.
+- **Host layers must be declared before `layerpro`** to outrank it. Declare the
+  full order in the host stylesheet, otherwise the host layer is created after
+  LayerPro's and loses:
+
+  ```css
+  @layer app, layerpro;
+  ```
+
+- **`!important` inverts layer order.** A host `!important` rule is *weaker*
+  than LayerPro's `!important` rules, because LayerPro's live inside a layer
+  and host `!important` rules are unlayered. Do not rely on `!important` to
+  override LayerPro - use plain rules or a host layer declared before
+  `layerpro`.
+
+## Dock
+
+Popups that can be minimized share a dock, a taskbar-like strip pinned to the bottom of the viewport. The dock is mounted directly in `<body>` and it stays visible while the page scrolls.
+
+While the dock is mounted LayerPro puts the `layerpro-dock` class on `<html>` and `<body>`:
+
+```css
+html.layerpro-dock { height: 100%; overflow: hidden; }
+body.layerpro-dock { position: absolute; top: 0; right: 0; bottom: var(--dock-height); left: 0; overflow-y: auto; }
+```
+
+The body is lifted from the bottom, so the strip used by the dock stays free and the page content is never covered by it. The class is removed as soon as the last popup is closed, so the host page is left exactly as it was. No inline style is written on the host page.
+
+> **Note:** while the dock is open the body is the scrolling element, so `window.scrollY` stays `0` and page level scroll listeners do not fire. Host the scrolling in an inner container if the page needs it.
+
+## 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()`). For strict CSP environments, the injected stylesheet auto-detects the nonce from `window.__layerproNonce`, existing `<style>`/`<script>` elements, or `document.body.dataset.nonce`. Alternatively, import the stylesheet as a static file via `import 'layerpro/style.css'` to avoid inline style injection entirely. Use `layerpro.config({ nonce })` for explicit nonce control.
+- **No global side effects** - `import 'layerpro'` does NOT override `window.alert`/`confirm`/`prompt`. Use `import 'layerpro/global'` or `layerpro.installGlobals()` to opt in to the global overrides.
 
 ## License