layerpro 4.0.0 → 4.1.0

package/llms.txt

@@ -1,22 +1,28 @@
 # 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
 
 - [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/dom.ts](core/dom.ts): jQuery-free chainable DOM helper (`LpEl`, `lp`, `lpAll`, `lpCreate`, `lpDoc`, `lpWin`) - the replacement for jQuery. Document aware: elements are created and resolved in the document of the scope they belong to.
+- [core/scope.ts](core/scope.ts): The scope of a layer - the (window, document) pair it is drawn in. Resolves a target (native window id, Window, scope) into a scope and keeps the scope of every open layer.
 - [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/genLayer.ts](core/genLayer.ts): DOM builder for a popup, dock/buttons wiring, pointer/click/dblclick handlers. The window surface is a native `<dialog>`, shown with `show()`; the confirm/cancel row lives in `.popup_internal` (not in the body), so a React body cannot wipe it.
 - [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
@@ -40,6 +46,9 @@
 ## Key behaviors
 
 - **jQuery removed** - all DOM via `core/dom.ts`; public API unchanged.
+- **Windows are native `<dialog>` elements** - shown with `show()` (not `showModal()`), so the element stays in the normal flow and the LayerPro geometry, drag, resize and stacking order are unchanged. The UA look (canvas background, padding, border, auto margin) is reset by the stylesheet.
+- **The button row is outside the body** - the `buttons` option renders its row in `.popup_internal`, next to the body, and reuses it on every re-open. React owns the body container and empties it on commit, so a row inside the body would be wiped.
+- **Target window** - `props.target` names the window a layer is drawn in (native window id, Window, or scope); `layerpro.window(target)` returns a handle bound to that window; the modals accept `{ target }`. Without a target a layer is drawn in the document of the realm that loaded LayerPro.
 - **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.

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,17 @@ 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. [Targeting a window](#targeting-a-window)
+7. [Options Reference](#options-reference)
+8. [Dock & Taskbar](#dock--taskbar)
+9. [Maximize & Minimize](#maximize--minimize)
+10. [Dragging & Resizing](#dragging--resizing)
+11. [React Body](#react-body)
+12. [Selection & z-index](#selection--z-index)
+13. [API Methods](#api-methods)
+14. [Styling & z-index](#styling--z-index)
+15. [Notes & Migration](#notes--migration)
 
 ---
 
@@ -129,6 +135,100 @@ 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: "📊",
+  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.
+
+---
+
+## Targeting a window
+
+Every layer belongs to one window: the document it is drawn in. By default
+that is the document of the page that loaded LayerPro. The `target` option
+names another window, so a window opened with `native: true` can host its
+own layers instead of seeing them land on the opener.
+
+```javascript
+// A real browser window
+await layerpro.popup.open({
+  id: "desk",
+  name: "Desktop",
+  native: true
+});
+
+// A layer inside that window
+await layerpro.popup.open({
+  id: "detail",
+  body: "<p>Inside the desk</p>",
+  target: "desk"
+});
+
+// The handle bound to that window does the same
+const desk = layerpro.window("desk");
+await desk.popup.open({ id: "detail2", body: "<p>Also inside</p>" });
+
+// The modals accept a target too
+await layerpro.confirm("Save the changes?", { target: "desk" });
+```
+
+A target is one of:
+
+| Target | Meaning |
+|--------|---------|
+| `string` / `number` | the id of a native window opened by LayerPro |
+| `Window` | that browser window, when it is reachable (same origin) |
+| `{ win, doc }` | an explicit scope |
+
+The target window carries the LayerPro stylesheet, so a layer drawn there
+looks exactly like a layer drawn on the page. A target that cannot be
+reached (unknown id, closed window, another origin) produces a warning and
+the layer is drawn in the current document.
+
+---
+
 ## Options Reference
 
 ```typescript
@@ -169,8 +269,13 @@ layerpro.popup.open({
   dockable?: boolean,         // show an icon in the dock bar
   close?: boolean,            // show the close button
    modal?: boolean,          // show a full-screen overlay that blocks pointer events beneath
-}
-```
+
+  // The window the layer is drawn in: the id of a native window, a Window
+  // object, or a { win, doc } scope. Without it the layer is drawn in the
+  // document of the page that loaded LayerPro.
+  target?: string | number | Window | LayerScope,
+}
+```
 
 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.
@@ -280,6 +385,11 @@ layerpro.popup.open({
 
 React state, effects, and context all work normally inside the body.
 
+The body container belongs to React: React empties it when it commits the first
+render. Anything LayerPro needs to keep inside the window is therefore drawn in
+the internal area (`.popup_internal`), next to the body - this is where the
+confirm/cancel row lives, so a React body can never wipe it.
+
 ---
 
 ## Selection & z-index
@@ -312,6 +422,7 @@ layerpro.popup.index({ id: "myModal" });
 | `layerpro.popup.cleanupEvents(id)` | Remove dock/button/esc listeners |
 | `layerpro.popup.unmount(id)` | Unmount the React root (memory cleanup) |
 | `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.window(target)` | A handle bound to one window: `win`, `doc` and a `popup` API whose layers are drawn in that window |
 | `layerpro.installGlobals()` | Explicitly install global `alert`/`confirm`/`prompt`/`message` overrides (opt-in in 4.0) |
 
 ---
@@ -347,6 +458,116 @@ Stable class names (`.popup_bar`, `.popup_window`, `.popup_overflow`,
 `.popup_modal`) are emitted alongside the per-id classes so themes can target
 elements without attribute selectors.
 
+The window surface itself is a native `<dialog>` element: it is shown with
+`show()` (not `showModal()`), so it stays in the normal flow and the LayerPro
+geometry and stacking order keep working. The native look of the element
+(canvas background, padding, border, auto margin) is reset by the LayerPro
+stylesheet, so a theme keeps painting the window exactly as before.
+
+The confirm/cancel row built from the `buttons` option is a child of
+`.popup_internal`, **next to** the body and not inside it: React owns the body
+container and empties it when it commits, so a row kept inside the body was
+wiped by the first render. Target it with `.buttons` (or `.lp_confirm` /
+`.lp_cancel`), never with `.popup_body .buttons`. The built-in
+`alert` / `confirm` / `prompt` / `message` modals carry their own row inside
+their body markup.
+
+### 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": "4.0.0",
+  "version": "4.1.0",
   "description": "The real custom modals, alert, confirm, prompt... for your browser",
   "main": "./index.cjs",
   "module": "./index.js",

package/types/layerpro.d.ts

@@ -18,6 +18,49 @@ interface LayerButtonsConfig {
   cancel?: LayerButtonConfig
 }
 
+/**
+ * The window and the document a layer is drawn in.
+ * A layer always belongs to one scope: the document of the window it was
+ * opened in.
+ */
+interface LayerScope {
+  win: Window
+  doc: Document
+}
+
+/**
+ * Everything that can name the window a layer is drawn in:
+ *  - a popup id   -> the native browser window opened with that id
+ *  - a Window     -> that window, when it is reachable (same origin)
+ *  - a LayerScope -> that scope
+ */
+type LayerTarget = string | number | Window | LayerScope
+
+/** Options accepted by the modals. */
+interface LayerModalOptions {
+  /** The window the modal is drawn in. */
+  target?: LayerTarget
+}
+
+/** A handle bound to one window, used to open layers in that window. */
+interface LayerWindow {
+  /** The target this handle is bound to. */
+  readonly id: string | number | Window
+  /** The browser window, when it can be reached. */
+  readonly win: Window | null
+  /** The document of the window, when it can be reached. */
+  readonly doc: Document | null
+  /** The popup API, bound to that window. */
+  readonly popup: {
+    open: (props: GenLayerProps) => Promise<GenLayerProps>
+    close: (id: string | number | GenLayerProps | null | undefined) => void
+    center: (id: string | number | GenLayerProps, offset?: number) => void
+    maximize: (props: GenLayerProps) => void
+    iconize: (id: string | number | GenLayerProps) => void
+    index: (id: string | number | GenLayerProps) => void
+  }
+}
+
 interface GenLayerProps {
   id: string | number
   body?: React.ReactElement | string | HTMLElement
@@ -61,6 +104,28 @@ interface GenLayerProps {
   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
+  /**
+   * The window this layer is drawn in. Without a target the layer is drawn
+   * in the document of the realm that loaded LayerPro.
+   */
+  target?: LayerTarget
 }
 
 /**
@@ -78,15 +143,21 @@ interface GenLayerProps {
     config: (opts: { nonce?: string }) => void
 
     /** Open a LayerPro alert. Returns a Promise that resolves when the popup closes. */
-    readonly alert: (txt: string) => Promise<void>
+    readonly alert: (txt: string, opts?: LayerModalOptions) => Promise<void>
     /** Open a LayerPro prompt. Returns a Promise that resolves to the input string. */
-    readonly prompt: (txt: string, defaultValue?: string) => Promise<string>
+    readonly prompt: (txt: string, defaultValue?: string, opts?: LayerModalOptions) => Promise<string>
     /** Open a LayerPro message popup. Returns a Promise that resolves when it closes. */
-    readonly message: (txt: string) => Promise<void>
+    readonly message: (txt: string, opts?: LayerModalOptions) => Promise<void>
     /** Open a LayerPro confirm. Returns a Promise that resolves to a boolean. */
-    readonly confirm: (txt: string) => Promise<boolean>
+    readonly confirm: (txt: string, opts?: LayerModalOptions) => Promise<boolean>
     readonly credits: (props: { name: string, version: string, description: string, license: string, author: { name: string, email: string } }) => void
 
+    /**
+     * A handle bound to one window. Every layer opened through the handle is
+     * drawn in that window, not in the one that loaded LayerPro.
+     */
+    readonly window: (target: string | number | Window) => LayerWindow
+
     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`
@@ -107,10 +178,12 @@ interface GenLayerProps {
       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
+      zIndex: (scope?: LayerScope) => number
       useReactAdapter?: (props: GenLayerProps, container: HTMLElement) => void
     }