layerpro 4.0.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
 
@@ -17,6 +21,7 @@
 - [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

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)
 
 ---
 
@@ -129,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: "📊",
+  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
@@ -347,6 +401,102 @@ 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.
 
+### 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.0.1",
   "description": "The real custom modals, alert, confirm, prompt... for your browser",
   "main": "./index.cjs",
   "module": "./index.js",

package/types/layerpro.d.ts

@@ -61,6 +61,23 @@ 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
 }
 
 /**
@@ -107,6 +124,8 @@ 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. */