layerpro 4.0.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!");
-
-confirm("Are you sure?", () => {
-  console.debug("User clicked YES");
-});
+layerpro.alert("Hello World!");                       // Promise<void>
+layerpro.message("Operation complete!");              // Promise<void>
 
-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.
@@ -273,6 +321,7 @@ const val = await prompt("Name?");        // Promise<string>
 | `popup.movable(props)` | Enable dragging. |
 | `popup.resizable(props)` | Enable resizing. |
 | `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
@@ -298,6 +347,187 @@ The title bar, window surface, internal area, and body all read from CSS custom
  | `--modal-background` | modal overlay |
 | `--popup-z-index` | base z-index for the stack |
 
+Additional variables available for buttons, inputs, resize handles, and the dock:
+
+| 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`:
+
+```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;
+}
+```
+
+> **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;
+}
+```
+
+### 3. Cascade layers (full control)
+
+All LayerPro styles live inside the CSS cascade layer `layerpro`, so a host app can restyle the popups without `!important` or fragile selectors.
+
+```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.