layerpro 3.3.0 → 4.0.0

package/llms.txt

@@ -1,55 +1,57 @@
-# 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.
-
-## Source
-
-- [index.ts](index.ts): Entry point. Sets `window.layerpro` (frozen, non-enumerable), imports SCSS, initializes mode.
-- [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/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/namespace.ts](core/namespace.ts): Global namespace setup.
-
-## Types
-
-- [types/layerpro.d.ts](types/layerpro.d.ts): Public TypeScript definitions (`GenLayerProps`, the `layerpro` global, `Window`/`globalThis` augmentations).
-
-## Docs
-
-- [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.
-
-## Build & Config
-
-- [package.json](package.json): Manifest. React/react-dom are `devDependencies` (external at runtime); **jQuery removed**. `main`/`browser` → `index.js` (ESM), `exports.import` → `index.js`.
-- [tsup.config.ts](tsup.config.ts): Build (CJS + ESM, terser minify, esbuild-sass-plugin). Externalizes devDependencies.
-- [tsup.plugin.copyStatic.ts](tsup.plugin.copyStatic.ts): Copies static files (README, types, license) into `dist`.
-- [tsup.plugin.injectCss.ts](tsup.plugin.injectCss.ts): Injects compiled SCSS into the bundle.
-
-## Key behaviors
-
-- **jQuery removed** — all DOM via `core/dom.ts`; public API unchanged.
-- **React external** — only the modal `body` is rendered with `react-dom` `createRoot`.
-- **Instant resize** — CSS `transition` disabled on the popup while resizing (no lag).
-- **Maximize is pure CSS** — `position: fixed` + insets; follows viewport with no JS listeners.
-- **Dock = OS taskbar** — click dock icon toggles restore / focus / minimize.
-- **z-index** — set as unitless numbers; the base is read from the `--popup-z-index` CSS variable (default `1000`). Clicking the body or title bar selects (brings to front).
-
-## Contributing
-
-LayerPro is **open source** and free to use. The current codebase is private, but
-**anyone is welcome to join**. If you would like to contribute, suggest changes,
-or just chat about the project, contact the author:
-
-- **Dario Passariello** — https://dario.passariello.ca/ — dariopassariello@gmail.com
-
-Participation is voluntary and free; everyone is free to take part.
+# 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.
+
+## Source
+
+- [index.ts](index.ts): Entry point. Sets `window.layerpro` (frozen, non-enumerable), imports SCSS, initializes mode.
+- [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/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/namespace.ts](core/namespace.ts): Global namespace setup.
+
+## Types
+
+- [types/layerpro.d.ts](types/layerpro.d.ts): Public TypeScript definitions (`GenLayerProps`, the `layerpro` global, `Window`/`globalThis` augmentations).
+
+## Docs
+
+- [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.json](package.json): Manifest. React/react-dom are `devDependencies` (external at runtime); **jQuery removed**. `main`/`browser` → `index.js` (ESM), `exports.import` → `index.js`.
+- [tsup.config.ts](tsup.config.ts): Build (CJS + ESM, terser minify, esbuild-sass-plugin). Externalizes devDependencies.
+- [tsup.plugin.copyStatic.ts](tsup.plugin.copyStatic.ts): Copies static files (README, types, license) into `dist`.
+- [tsup.plugin.injectCss.ts](tsup.plugin.injectCss.ts): Injects compiled SCSS into the bundle.
+
+## Key behaviors
+
+- **jQuery removed** - all DOM via `core/dom.ts`; public API unchanged.
+- **React external** - only the modal `body` is rendered with `react-dom` `createRoot`.
+- **Instant resize** - CSS `transition` disabled on the popup while resizing (no lag).
+- **Maximize is pure CSS** - `position: fixed` + insets; follows viewport with no JS listeners.
+- **Dock = OS taskbar** - click dock icon toggles restore / focus / minimize.
+- **z-index** - set as unitless numbers; the base is read from the `--popup-z-index` CSS variable (default `1000`). Clicking the body or title bar selects (brings to front).
+
+## Contributing
+
+LayerPro is **open source** and free to use. The current codebase is private, but
+**anyone is welcome to join**. If you would like to contribute, suggest changes,
+or just chat about the project, contact the author:
+
+- **Dario Passariello** - https://dario.passariello.ca/ - dariopassariello@gmail.com
+
+Participation is voluntary and free; everyone is free to take part.

package/markdown/GUIDE.md

@@ -1,6 +1,6 @@
 # LayerPro Guide
 
-> A practical, example-driven guide to LayerPro — the real custom modals
+> A practical, example-driven guide to LayerPro - the real custom modals
 > (alert, confirm, prompt, message) and advanced popups for the browser.
 
 LayerPro is **dependency-free**: it no longer uses jQuery. All DOM work is done
@@ -50,18 +50,17 @@ Import LayerPro once at your app entry point. It overrides the global
 import "layerpro";
 ```
 
-That single import is enough — `window.layerpro` becomes available and the
+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>
 > ```
 
 ---
@@ -169,19 +168,18 @@ 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>`)
-> that intercepts every pointer event — the page underneath becomes unclickable
-> until the popup closes. This is modal behavior; 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.
 
-> **Duplicate id** — opening a popup whose `id` already exists brings that window
+> **Duplicate id** - opening a popup whose `id` already exists brings that window
 > to the front and refreshes its `body`/`buttons` instead of doing nothing.
 
 ---
@@ -189,7 +187,7 @@ Pass `center: true` to force centering regardless of the position props.
 ## Dock & Taskbar
 
 When `dockable` and `iconize` are enabled, a minimized popup becomes an icon in
-the bottom dock bar — exactly like an OS taskbar:
+the bottom dock bar - exactly like an OS taskbar:
 
 ```javascript
 layerpro.popup.open({
@@ -215,7 +213,7 @@ The close `✕` on the dock icon closes the popup completely.
 ## Maximize & Minimize
 
 Maximize is implemented with **pure CSS** (`position: fixed` + `inset`), so the
-popup fills the viewport and follows window resizing automatically — no JS
+popup fills the viewport and follows window resizing automatically - no JS
 resize listeners are involved.
 
 ```javascript
@@ -313,7 +311,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,12 +339,12 @@ 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.
 
 ---
@@ -364,4 +363,4 @@ elements without attribute selectors.
 
 ---
 
-© [Dario Passariello](https://dario.passariello.ca/) — MIT License
+© [Dario Passariello](https://dario.passariello.ca/) - MIT License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "layerpro",
   "codeName": "layerpro",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "The real custom modals, alert, confirm, prompt... for your browser",
   "main": "./index.cjs",
   "module": "./index.js",
@@ -18,6 +18,12 @@
       "require": "./react.cjs",
       "types": "./react.d.ts"
     },
+    "./global": {
+      "import": "./global.js",
+      "require": "./global.cjs",
+      "types": "./global.d.ts"
+    },
+    "./style.css": "./index.css",
     "./types/*": "./types/*"
   },
   "license": "MIT",
@@ -66,8 +72,13 @@
     "llms.txt",
     "package.json",
     "react.cjs",
+    "react.d.ts",
     "react.js",
+    "global.cjs",
+    "global.d.ts",
+    "global.js",
     "README.md",
+    "SECURITY-HARDENING.md",
     "SECURITY.md"
   ],
   "peerDependencies": {
@@ -79,9 +90,6 @@
     "url": "https://dario.passariello.ca/",
     "email": "dariopassariello@gmail.com"
   },
-  "resolutions": {
-    "esbuild": "^0.25.0"
-  },
   "overrides": {
     "esbuild": "^0.28.2"
   },

package/react.d.ts

@@ -0,0 +1,32 @@
+/// <reference path="./types/layerpro.d.ts" />
+/// <reference types="react" />
+
+import type { GenLayerProps } from "./types/layerpro"
+
+/**
+ * React adapter for LayerPro - powered by reattach.
+ *
+ * Lazily loaded by the core when a React element is passed as a layer body.
+ * This keeps react-dom out of the core bundle.
+ *
+ * reattach handles root creation, root reuse on duplicate-id reopen,
+ * context bridging (inheritContext), and auto-healing DOM (resilient).
+ *
+ * @param props - The layer props containing a ReactElement body
+ * @param container - The DOM node to mount into
+ */
+declare function renderReactBody(
+  props: GenLayerProps,
+  container: HTMLElement
+): void
+
+/**
+ * Unmount a previously mounted React body via reattach.
+ * Called by LayerPro's close() lifecycle to prevent memory leaks.
+ *
+ * @param id - The layer ID (same as props.id used in renderReactBody)
+ */
+declare function unmountReactBody(id: string): void
+
+export { unmountReactBody }
+export default renderReactBody

package/types/layerpro.d.ts

@@ -1,23 +1,12 @@
 /// <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
-
-///
+/**
+ * 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
@@ -63,7 +52,7 @@ interface GenLayerProps {
 
   resizable?: boolean
   close?: boolean
-  raised?: boolean
+  /** Modal overlay - intercepts pointer events on the underlying page. */
   modal?: boolean
   iconize?: boolean
   center?: boolean
@@ -77,57 +66,69 @@ interface GenLayerProps {
 /**
  * Interface for the layerpro object
  */
-interface _layerpro {
-
-  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
-  }
+  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
+       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
+    }
 
-}
+  }
 
 /**
- * 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.
+ * 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
-type popup = layerpro
+declare var popup: _layerpro['popup']
+type popup = _layerpro['popup']