layerpro 3.4.0 → 4.0.1

package/llms.txt

@@ -1,9 +1,13 @@
 # LayerPro
 
-> Dependency-free custom modals (alert, confirm, prompt, message) and advanced
-> popups for the browser. Vanilla DOM (no jQuery); React/react-dom are external
-> and used only to render the modal body. Dockable, draggable, resizable,
-> maximizable (pure CSS), with an OS-style taskbar.
+> Browser window system: OS-style windows (draggable, resizable, maximizable,
+> dockable) that host any content, including React components. Also provides
+> Promise-based custom modals (alert, confirm, prompt, message) as a drop-in
+> replacement for the browser's native ones. Vanilla DOM (no jQuery);
+> React/react-dom are external and used only to render the modal body.
+> Dockable, draggable, resizable, maximizable (pure CSS), with an OS-style
+> taskbar. Fully themeable via CSS custom properties or the `layerpro` cascade
+> layer - see "Overriding the CSS" in the README.
 
 ## Source
 
@@ -11,11 +15,13 @@
 - [core/dom.ts](core/dom.ts): jQuery-free chainable DOM helper (`LpEl`, `lp`, `lpAll`, `lpCreate`, `lpDoc`, `lpWin`) - the replacement for jQuery.
 - [core/properties.ts](core/properties.ts): The `popup` object - `open`, `close`, `center`, `maximize`, `iconize`, `index`, `zIndex`, `movable`, `resizable`, `cleanupEvents`, `unmount`.
 - [core/genLayer.ts](core/genLayer.ts): DOM builder for a popup, dock/buttons wiring, pointer/click/dblclick handlers.
-- [core/message.ts](core/message.ts): `alert`/`confirm`/`message`/`prompt` implementations; overrides `window.alert`/`confirm`/`prompt` (callback-based, NOT synchronous) and provides `layerpro.noGlobals()` to restore natives.
+- [core/accessibility.ts](core/accessibility.ts): ARIA attributes, focus save/restore, Tab focus trap.
+- [core/message.ts](core/message.ts): `alert`/`confirm`/`message`/`prompt` - Promise-based (resolve on close); in 4.0 globals are opt-in via `layerpro/global`, `noGlobals` is removed.
 - [core/mode.ts](core/mode.ts): Close popups on orientation/size mode switch.
 - [core/mobile.ts](core/mobile.ts): Unified pointer/mouse/touch events (`getPointerDown`/`getPointerMove`/`getPointerUp`).
 - [core/window.ts](core/window.ts): Window-level helpers (scroll, size).
 - [core/credits.ts](core/credits.ts): Credits overlay helper.
+- [core/version.ts](core/version.ts): `layerpro.version()` - reads the current version from `app.json`.
 - [core/namespace.ts](core/namespace.ts): Global namespace setup.
 
 ## Types
@@ -27,6 +33,7 @@
 - [docs/README.md](docs/README.md): Project README (features, install, quick start).
 - [docs/markdown/GUIDE.md](docs/markdown/GUIDE.md): Example-driven usage guide (modals, popups, dock, maximize, resize, React body, API).
 - [docs/llms.txt](docs/llms.txt): This file.
+- [docs/SECURITY-HARDENING.md](docs/SECURITY-HARDENING.md): Security reference (CSP, XSS, SSRF, global overrides, accessibility).
 
 ## Build & Config
 

package/markdown/GUIDE.md

@@ -1,7 +1,10 @@
 # LayerPro Guide
 
-> A practical, example-driven guide to LayerPro - the real custom modals
-> (alert, confirm, prompt, message) and advanced popups for the browser.
+> A practical, example-driven guide to LayerPro - a browser window system that
+> generates OS-style windows (draggable, resizable, maximizable, dockable) able
+> to host any content, including React components, and that also provides
+> Promise-based custom modals (alert, confirm, prompt, message) as a drop-in
+> replacement for the browser's native ones.
 
 LayerPro is **dependency-free**: it no longer uses jQuery. All DOM work is done
 with small, chainable vanilla helpers. React and react-dom are the only
@@ -16,14 +19,16 @@ body when you pass a React element.
 2. [Quick Start](#quick-start)
 3. [Basic Modals](#basic-modals)
 4. [Custom Popups](#custom-popups)
-5. [Options Reference](#options-reference)
-6. [Dock & Taskbar](#dock--taskbar)
-7. [Maximize & Minimize](#maximize--minimize)
-8. [Dragging & Resizing](#dragging--resizing)
-9. [React Body](#react-body)
-10. [Selection & z-index](#selection--z-index)
-11. [API Methods](#api-methods)
-12. [Notes & Migration](#notes--migration)
+5. [OS-style Windows](#os-style-windows)
+6. [Options Reference](#options-reference)
+7. [Dock & Taskbar](#dock--taskbar)
+8. [Maximize & Minimize](#maximize--minimize)
+9. [Dragging & Resizing](#dragging--resizing)
+10. [React Body](#react-body)
+11. [Selection & z-index](#selection--z-index)
+12. [API Methods](#api-methods)
+13. [Styling & z-index](#styling--z-index)
+14. [Notes & Migration](#notes--migration)
 
 ---
 
@@ -53,15 +58,14 @@ import "layerpro";
 That single import is enough - `window.layerpro` becomes available and the
 global `alert`/`confirm`/`prompt` are replaced, and a `message` global is added.
 
-> **⚠️ Global override contract:** the overridden `confirm()` no longer returns a
-> `boolean` and `prompt()` no longer returns a `string` - they are callback-based
-> and return `undefined`. If your codebase (or a third-party dependency) relies on
-> the native synchronous return values, call `layerpro.noGlobals()` right after
-> importing to restore the originals:
+> **⚠️ Global override note:** in 4.0, `import 'layerpro'` does **not** override
+> `window.alert`/`confirm`/`prompt`/`message`. The library methods
+> (`layerpro.alert`, `layerpro.confirm`, etc.) return Promises. To override the
+> browser globals with Promise-based versions, import the explicit entry point:
 >
 > ```javascript
-> import "layerpro";
-> layerpro.noGlobals();   // restores native alert/confirm/prompt, drops `message`
+> import "layerpro/global";  // opt-in to global overrides
+> await confirm("Sure?");     // Promise<boolean>
 > ```
 
 ---
@@ -130,6 +134,55 @@ layerpro.popup.open({
 
 ---
 
+## OS-style Windows
+
+A popup is not limited to a modal dialog. With `movable`, `resizable`,
+`maximize`, `iconize` and `dockable` enabled 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
+layerpro.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
+});
+```
+
+With a React component inside, this becomes a real application window rendered
+in the page with native-looking chrome:
+
+```jsx
+layerpro.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
+});
+```
+
+> `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.
+
+---
+
 ## Options Reference
 
 ```typescript
@@ -169,17 +222,16 @@ layerpro.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 - show a full-screen overlay that
-  modal?: boolean,            //     blocks pointer events to the page underneath
-}
+   modal?: boolean,          // show a full-screen overlay that blocks pointer events beneath
+}
 ```
 
 If `top/left/right/bottom` are all `0` (or unset) the popup is auto-centered.
 Pass `center: true` to force centering regardless of the position props.
 
-> **`raised` / `modal`** injects a full-viewport overlay (`popup_raised_<id>`)
+> **`modal`** injects a full-viewport overlay (`popup_modal_<id>`)
 > that intercepts every pointer event - the page underneath becomes unclickable
-> until the popup closes. This is modal behavior; both names are accepted.
+> until the popup closes.
 
 > **Duplicate id** - opening a popup whose `id` already exists brings that window
 > to the front and refreshes its `body`/`buttons` instead of doing nothing.
@@ -313,7 +365,8 @@ layerpro.popup.index({ id: "myModal" });
 | `layerpro.popup.store(element)` | Store a reference (placeholder/extensibility) |
 | `layerpro.popup.cleanupEvents(id)` | Remove dock/button/esc listeners |
 | `layerpro.popup.unmount(id)` | Unmount the React root (memory cleanup) |
-| `layerpro.noGlobals()` | Restore native `alert`/`confirm`/`prompt`; remove `message` |
+| `layerpro.config(opts)` | Runtime config. Supports `{ nonce: string }` for CSP; sets `window.__layerproNonce`. Call before importing LayerPro for the nonce to be present at CSS injection time |
+| `layerpro.installGlobals()` | Explicitly install global `alert`/`confirm`/`prompt`/`message` overrides (opt-in in 4.0) |
 
 ---
 
@@ -340,14 +393,110 @@ properties, so theming needs no `!important` and no `[class^=popup_…]` selecto
 | `--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` (in root.scss) | base z-index for the stack |
 
 Stable class names (`.popup_bar`, `.popup_window`, `.popup_overflow`,
 `.popup_internal`, `.popup_body`, `.popup_drag`, `.popup_icon`, `.popup_option`,
-`.popup_raised`) are emitted alongside the per-id classes so themes can target
+`.popup_modal`) are emitted alongside the per-id classes so themes can target
 elements without attribute selectors.
 
+### Overriding the CSS
+
+LayerPro never writes a plain inline style: every declaration lives in the
+stylesheet and is driven by a **class** (the state) or by a **CSS custom
+property** (the value). That means any part of a window can be restyled with
+a plain CSS rule - nothing needs `!important` to win over an inline style.
+
+There are three ways to restyle LayerPro, from the most recommended to the most
+surgical.
+
+**1. CSS custom properties (recommended).** Every visual detail is driven by a
+variable on `:root`, so theming needs no selectors and 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, because every window lives inside
+`#popup`:
+
+```css
+#popup .popup_window_myDarkPopup {
+  --window-background: #000;
+  --bar-background: #000;
+}
+```
+
+**2. Target the generated classes.** Each element carries a stable class alias
+next to its id-suffixed class:
+
+```css
+#popup .popup_window { border-radius: 0; }
+#popup .buttons button { background: #2563eb; }
+#popup .popup_option .close:hover { background: #dc2626; }
+#popup_dock { background: #111827; }
+```
+
+The visual **states** are classes too, so they can be restyled like any other
+element:
+
+| Class | Applied when |
+|-------|--------------|
+| `.popup_maximized` | the window is maximized |
+| `.popup_iconized` | the window is minimized to the dock |
+| `.popup_dimmed` | another window has the focus |
+| `.popup_content_hidden` | another window has the focus |
+| `.popup_content_visible` | the window has the focus |
+| `.lp_hidden` | the element is hidden |
+| `.lp_fade_in` / `.lp_fade_out` | during a fade |
+| `.lp_no_pointer` | while dragging/resizing |
+| `.lp_no_touch` | on the drag/resize handles |
+| `.lp_no_transition` | while resizing |
+
+```css
+#popup .popup_maximized { inset: 0; bottom: 0; }
+#popup .popup_dimmed { opacity: .8; }
+```
+
+The geometry of a window is carried by custom properties, so it can be
+overridden as well: `--lp-top`, `--lp-left`, `--lp-right`, `--lp-bottom`,
+`--lp-width`, `--lp-height`, `--lp-min-width`, `--lp-min-height`,
+`--lp-max-width`, `--lp-max-height`, `--lp-z-index`.
+
+```css
+#popup .popup_overflow { --lp-left: 50%; --lp-top: 100px; }
+```
+
+**3. Cascade layers (full control).** All LayerPro styles live inside the CSS
+cascade layer `layerpro`. Unlayered host rules always win, so a host stylesheet
+can restyle the popups without `!important`:
+
+```css
+#popup { border-radius: 4px; }
+```
+
+If the host declares its own layer, it must be declared **before** `layerpro`,
+otherwise it loses:
+
+```css
+@layer app, layerpro;
+```
+
+> Do **not** rely on `!important` to override LayerPro: LayerPro's `!important`
+> rules live inside a layer and are stronger than unlayered host `!important`
+> rules. Use plain rules or a host layer declared before `layerpro`.
+
 ---
 
 ## Notes & Migration

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "layerpro",
   "codeName": "layerpro",
-  "version": "3.4.0",
+  "version": "4.0.1",
   "description": "The real custom modals, alert, confirm, prompt... for your browser",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -18,6 +18,11 @@
       "require": "./react.cjs",
       "types": "./react.d.ts"
     },
+    "./global": {
+      "import": "./global.js",
+      "require": "./global.cjs",
+      "types": "./global.d.ts"
+    },
     "./style.css": "./index.css",
     "./types/*": "./types/*"
   },
@@ -69,7 +74,11 @@
     "react.cjs",
     "react.d.ts",
     "react.js",
+    "global.cjs",
+    "global.d.ts",
+    "global.js",
     "README.md",
+    "SECURITY-HARDENING.md",
     "SECURITY.md"
   ],
   "peerDependencies": {
@@ -81,9 +90,6 @@
     "url": "https://dario.passariello.ca/",
     "email": "dariopassariello@gmail.com"
   },
-  "resolutions": {
-    "esbuild": "^0.25.0"
-  },
   "overrides": {
     "esbuild": "^0.28.2"
   },

package/types/layerpro.d.ts

@@ -1,143 +1,153 @@
-/// <reference types="react" />
-
-/** Generate custom alert using alert([text]) */
-declare function alert(f1?: string): void
-
-/** Generate custom confirm using confirm([text],[callback for YES],[optional callback for NO])
- *  WARNING: This overrides the native confirm(). The return value is NOT a usable
- *  boolean - callbacks are invoked asynchronously instead. Never rely on the
- *  return value; use the yes/no callbacks. */
-declare function confirm(message: string, func1: (yes: boolean) => void, func2?: (no: boolean) => void): void
-
-/** Generate custom message using message([text],[callback]) and option callback */
-declare function message(f1?: string, func1?: () => void): void
-
-/** Generate custom prompt using prompt([text],[callback]) and option callback
- *  WARNING: This overrides the native prompt(). The return value is NOT a usable
- *  string - use the callback to receive the input. */
-declare function prompt(f1?: string, func1?: (input: string) => void): void
-
-///
-
-interface LayerButtonConfig {
-  text: string
-  cb?: () => void
-}
-
-interface LayerButtonsConfig {
-  confirm?: LayerButtonConfig
-  cancel?: LayerButtonConfig
-}
-
-interface GenLayerProps {
-  id: string | number
-  body?: React.ReactElement | string | HTMLElement
-  name?: string
-  style?: Record<string, string | number>
-  class?: string
-  icon?: string
-
-  buttons?: LayerButtonsConfig
-
-  top?: number | string
-  left?: number | string
-  right?: number | string
-  bottom?: number | string
-
-  width?: number | string
-  height?: number | string
-
-  minWidth?: number
-  minHeight?: number
-  maxWidth?: number
-  maxHeight?: number
-
-  fadeIn?: number
-  fadeOut?: number
-  timer?: number
-
-  maximize?: boolean
-  isMaximize?: boolean
-  dockable?: boolean
-  movable?: boolean
-
-  resizable?: boolean
-  close?: boolean
-  raised?: boolean
-  modal?: boolean
-  iconize?: boolean
-  center?: boolean
-
-  source?: string
-  store?: unknown
-  inheritContext?: boolean
-  resilient?: boolean
-}
-
-/**
-   * Interface for the layerpro object
-   */
-  interface _layerpro {
-
-    /** Optional CSP nonce. Set via `layerpro.config({ nonce })` before importing
-     *  the CSS-in-JS bundle so the injected `<style>` element passes strict CSP.
-     *  If unset, the nonce is auto-detected from existing `<style>`/`<script>`
-     *  elements on the page. */
-    nonce?: string
-
-    /** Runtime configuration. Currently supports `{ nonce: string }` for CSP. */
-    config: (opts: { nonce?: string }) => void
-
-    readonly alert: (txt: string) => void
-  readonly prompt: (txt: string, callback: (input: string) => void) => void
-  readonly message: (txt: string, callback: () => void) => void
-  readonly confirm: (txt: string, yesCallback: () => void, noCallback?: () => void) => void
-  readonly credits: (props: { name: string, version: string, description: string, license: string, author: { name: string, email: string } }) => void
-
-  setProps: (obj: Record<string, unknown>, options?: { enumerable?: boolean, writable?: boolean }) => void
-
-  /** Remove the global alert/confirm/prompt/message overrides and restore
-   *  the native browser implementations. Call this right after importing
-   *  LayerPro if your codebase depends on synchronous native globals. */
-  readonly noGlobals: () => void
-
-  /** Opt-in to override the browser's native alert/confirm/prompt/message
-   *  globals with LayerPro's callback-based versions. This is opt-in so
-   *  libraries embedded in other applications do not silently change
-   *  global behavior. */
-  readonly installGlobals: () => void
-
-  readonly popup: {
-    open: (props: GenLayerProps) => GenLayerProps
-    center: (id: string | number | GenLayerProps, offset?: number) => void
-    maximize: (props: GenLayerProps) => void
-    iconize: (id: string | number | GenLayerProps) => void
-    movable: (props: GenLayerProps) => void
-    resizable: (props: GenLayerProps) => void
-    store: (element: unknown) => void
-    index: (id: string | number | GenLayerProps) => void
-    zIndex: (props?: GenLayerProps) => number
-    close: (id: string | number | GenLayerProps | null | undefined) => void
-    unmount: (id: string) => void
-    cleanupEvents: (id: string) => void
-    abortSource: (id: string) => void
-    useReactAdapter?: (props: GenLayerProps, container: HTMLElement) => void
-  }
-
-}
-
-/**
- * LayerPro overrides the native alert/confirm/prompt globals and adds a
- * `message` global. They are callback-based and do NOT return native values.
- * Call `layerpro.noGlobals()` to restore the synchronous natives.
- */
-interface Window {
-  layerpro: _layerpro
-  popup: _layerpro['popup']
-}
-
-declare var layerpro: _layerpro
-type layerpro = _layerpro
-
-declare var popup: _layerpro['popup']
-type popup = _layerpro['popup']
+/// <reference types="react" />
+
+/**
+ * LayerPro - the real custom modals for your browser.
+ *
+ * In 4.0, importing `layerpro` no longer overrides `window.alert` /
+ * `window.confirm` / `window.prompt` / `window.message`. To opt in to the
+ * global overrides, import the `layerpro/global` entrypoint instead.
+ */
+
+interface LayerButtonConfig {
+  text: string
+  cb?: () => void
+}
+
+interface LayerButtonsConfig {
+  confirm?: LayerButtonConfig
+  cancel?: LayerButtonConfig
+}
+
+interface GenLayerProps {
+  id: string | number
+  body?: React.ReactElement | string | HTMLElement
+  name?: string
+  style?: Record<string, string | number>
+  class?: string
+  icon?: string
+
+  buttons?: LayerButtonsConfig
+
+  top?: number | string
+  left?: number | string
+  right?: number | string
+  bottom?: number | string
+
+  width?: number | string
+  height?: number | string
+
+  minWidth?: number
+  minHeight?: number
+  maxWidth?: number
+  maxHeight?: number
+
+  fadeIn?: number
+  fadeOut?: number
+  timer?: number
+
+  maximize?: boolean
+  isMaximize?: boolean
+  dockable?: boolean
+  movable?: boolean
+
+  resizable?: boolean
+  close?: boolean
+  /** Modal overlay - intercepts pointer events on the underlying page. */
+  modal?: boolean
+  iconize?: boolean
+  center?: boolean
+
+  source?: string
+  store?: unknown
+  inheritContext?: boolean
+  resilient?: boolean
+
+  /**
+   * Open the layer inside a real browser window (`window.open`) instead of
+   * the in-page overlay. The window keeps the layer information: name, icon,
+   * dimensions, position, body and buttons.
+   */
+  native?: boolean
+  /**
+   * Save the position and the size of the window and restore them on the
+   * next open with the same id (stored in `localStorage`).
+   */
+  persist?: boolean
+  /**
+   * Close the native window when the page that opened it is closed.
+   * A reload/refresh of the opener does NOT close the native window.
+   */
+  closeWithOpener?: boolean
+}
+
+/**
+ * Interface for the layerpro object
+ */
+  interface _layerpro {
+
+    /** Optional CSP nonce. Set via `layerpro.config({ nonce })` before importing
+     *  the CSS-in-JS bundle so the injected `<style>` element passes strict CSP.
+     *  If unset, the nonce is auto-detected from existing `<style>`/`<script>`
+     *  elements on the page. */
+    nonce?: string
+
+    /** Runtime configuration. Currently supports `{ nonce: string }` for CSP. */
+    config: (opts: { nonce?: string }) => void
+
+    /** Open a LayerPro alert. Returns a Promise that resolves when the popup closes. */
+    readonly alert: (txt: string) => Promise<void>
+    /** Open a LayerPro prompt. Returns a Promise that resolves to the input string. */
+    readonly prompt: (txt: string, defaultValue?: string) => Promise<string>
+    /** Open a LayerPro message popup. Returns a Promise that resolves when it closes. */
+    readonly message: (txt: string) => Promise<void>
+    /** Open a LayerPro confirm. Returns a Promise that resolves to a boolean. */
+    readonly confirm: (txt: string) => Promise<boolean>
+    readonly credits: (props: { name: string, version: string, description: string, license: string, author: { name: string, email: string } }) => void
+
+    setProps: (obj: Record<string, unknown>, options?: { enumerable?: boolean, writable?: boolean, configurable?: boolean }) => void
+
+    /** Opt-in to override the browser's native `alert`/`confirm`/`prompt`/`message`
+     *  globals with LayerPro's Promise-based versions. Call this explicitly after
+     *  importing LayerPro - the default entry does **not** auto-override in 4.0.
+     *  Alternatively, use `import 'layerpro/global'`. */
+    readonly installGlobals: () => void
+
+    readonly popup: {
+      /** Open a modal; returns a Promise that resolves with the props when the popup closes. */
+      open: (props: GenLayerProps) => Promise<GenLayerProps>
+      center: (id: string | number | GenLayerProps, offset?: number) => void
+      maximize: (props: GenLayerProps) => void
+      iconize: (id: string | number | GenLayerProps) => void
+      movable: (props: GenLayerProps) => void
+      resizable: (props: GenLayerProps) => void
+      store: (element: unknown) => void
+      index: (id: string | number | GenLayerProps) => void
+      close: (id: string | number | GenLayerProps | null | undefined) => void
+      unmount: (id: string) => void
+      /** Remove a popup and its DOM synchronously. */
+      destroy: (id: string) => void
+       cleanupEvents: (id: string) => void
+       abortSource: (id: string) => void
+      /** @internal - managed internally for stacking order; do not call. */
+      zIndex: (props?: GenLayerProps) => number
+      useReactAdapter?: (props: GenLayerProps, container: HTMLElement) => void
+    }
+
+  }
+
+/**
+ * In 4.0, `layerpro` and `popup` are declared on `Window` but the native
+ * `alert`/`confirm`/`prompt`/`message` globals are NOT overridden by the
+ * default entry. Import `layerpro/global` to override them with Promise-based
+ * versions.
+ */
+interface Window {
+  layerpro: _layerpro
+  popup: _layerpro['popup']
+}
+
+declare var layerpro: _layerpro
+type layerpro = _layerpro
+
+declare var popup: _layerpro['popup']
+type popup = _layerpro['popup']