layerpro 4.0.1 → 4.1.0

package/llms.txt

@@ -12,9 +12,10 @@
 ## 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.
@@ -45,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

@@ -20,15 +20,16 @@ body when you pass a React element.
 3. [Basic Modals](#basic-modals)
 4. [Custom Popups](#custom-popups)
 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)
+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)
 
 ---
 
@@ -183,6 +184,51 @@ layerpro.popup.open({
 
 ---
 
+## 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
@@ -223,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.
@@ -334,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
@@ -366,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) |
 
 ---
@@ -401,6 +458,20 @@ 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "layerpro",
   "codeName": "layerpro",
-  "version": "4.0.1",
+  "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
@@ -78,6 +121,11 @@ interface GenLayerProps {
    * 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
 }
 
 /**
@@ -95,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`
@@ -129,7 +183,7 @@ interface GenLayerProps {
        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
     }