layerpro 3.1.0 → 3.1.5

package/markdown/GUIDE.md

@@ -1,367 +1,367 @@
-# LayerPro Guide
-
-> 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
-with small, chainable vanilla helpers. React and react-dom are the only
-external runtime dependencies, and they are used **only** to render the modal
-body when you pass a React element.
-
----
-
-## Table of Contents
-
-1. [Installation](#installation)
-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)
-
----
-
-## Installation
-
-```bash
-npm install layerpro
-```
-
-Or drop it straight into HTML (UMD build):
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/layerpro"></script>
-```
-
----
-
-## Quick Start
-
-Import LayerPro once at your app entry point. It overrides the global
-`alert`, `confirm`, `prompt`, and exposes `message` and `layerpro`:
-
-```javascript
-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:
->
-> ```javascript
-> import "layerpro";
-> layerpro.noGlobals();   // restores native alert/confirm/prompt, drops `message`
-> ```
-
----
-
-## Basic Modals
-
-```javascript
-// Simple alert
-alert("Hello World!");
-
-// Confirm with YES / NO callbacks
-confirm(
-  "Are you sure?",
-  () => console.debug("User clicked YES"),
-  () => console.debug("User clicked NO")
-);
-
-// Prompt with the typed value
-prompt("What is your name?", (name) => {
-  console.debug("User entered:", name);
-});
-
-// Plain message (auto-styled info box)
-message("Operation complete!", () => console.debug("message closed"));
-```
-
-> The global functions keep the same signatures you already know, so legacy
-> code keeps working.
-
----
-
-## Custom Popups
-
-Use `layerpro.popup.open(props)` for full control.
-
-```javascript
-layerpro.popup.open({
-  id: "myModal",
-  name: "My Modal",
-  body: "<p>Your <b>content</b> here</p>",
-  width: 450,
-  height: 350,
-  movable: true,
-  resizable: true,
-  maximize: true,
-  iconize: true,
-  dockable: true,
-  close: true,
-  buttons: {
-    confirm: { text: "OK", cb: () => layerpro.popup.close("myModal") },
-    cancel: { text: "Cancel", cb: () => layerpro.popup.close("myModal") }
-  }
-});
-```
-
-### The `body` parameter
-
-| Type | Example |
-|------|---------|
-| Plain text | `body: "Hello"` |
-| HTML string | `body: "<p>Hello</p>"` |
-| React element | `body: <MyComponent />` |
-
-> In React, always pass an **element** (`<Component />`), never a call
-> (`Component()`).
-
----
-
-## Options Reference
-
-```typescript
-{
-  id: string,                 // Unique id (auto-generated as popup_1, popup_2, … if omitted)
-  body: any,                  // text | HTML string | HTMLElement | React element
-  name: string,               // Title shown in the bar
-  icon: string,               // Icon glyph (HTML entity, e.g. "&#9888;") or HTML string
-                              //     (e.g. '<i class="fa fa-star"></i>')
-  class: string,              // Extra CSS class on the window
-
-  // Dimensions (defaults: width 340, height 220; minWidth 340, minHeight 220)
-  width?: number | string,
-  height?: number | string,
-  minWidth?: number,
-  minHeight?: number,
-  maxWidth?: number,
-  maxHeight?: number,
-
-  // Position (numbers are px; strings are applied as-is, e.g. "10%")
-  top?: number | string,
-  left?: number | string,
-  right?: number | string,
-  bottom?: number | string,
-  center?: boolean,           // Center in the viewport (adds a small cascade
-                              //     offset per open window so stacks don't overlap)
-
-  // Timing
-  fadeIn?: number,            // open fade duration (ms, default 100)
-  fadeOut?: number,           // close fade duration (ms, default 100)
-  timer?: number,             // auto-close after N ms
-
-  // Behavior flags
-  movable?: boolean,          // draggable by the title bar
-  resizable?: boolean,        // resize handles
-  maximize?: boolean,         // double-click title bar to maximize
-  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
-}
-```
-
-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.
-
-> **Duplicate id** — opening a popup whose `id` already exists brings that window
-> to the front and refreshes its `body`/`buttons` instead of doing nothing.
-
----
-
-## Dock & Taskbar
-
-When `dockable` and `iconize` are enabled, a minimized popup becomes an icon in
-the bottom dock bar — exactly like an OS taskbar:
-
-```javascript
-layerpro.popup.open({
-  id: "editor",
-  name: "Editor",
-  body: "<p>Edit something…</p>",
-  dockable: true,
-  iconize: true
-});
-```
-
-**Dock interactions (taskbar style):**
-
-- Click a dock icon of a **minimized** popup → it is restored and focused.
-- Click a dock icon of a popup that is open but **not focused** → it is brought
-  to the front.
-- Click a dock icon of the **focused** popup → it is minimized back to the dock.
-
-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
-resize listeners are involved.
-
-```javascript
-layerpro.popup.open({
-  id: "viewer",
-  name: "Viewer",
-  body: "<p>Big content</p>",
-  maximize: true,
-  iconize: true
-});
-```
-
-- **Double-click the title bar** → toggle maximize / restore.
-- **Click the dock icon** of a maximized popup → restore it.
-
-Because maximize is CSS-driven, resizing the browser window keeps the maximized
-popup perfectly aligned with no lag.
-
----
-
-## Dragging & Resizing
-
-Dragging and resizing are **instant**: the CSS `transition` is disabled on the
-popup while you drag a resize handle, so the popup tracks the pointer with no
-lag (especially on the bottom edge).
-
-```javascript
-layerpro.popup.open({
-  id: "panel",
-  name: "Panel",
-  body: "<p>Move and resize me</p>",
-  movable: true,
-  resizable: true
-});
-```
-
-- Drag the **title bar** to move.
-- Drag the **edges/corners** to resize.
-- These interactions are disabled automatically while a popup is maximized.
-
----
-
-## React Body
-
-Pass a React element as `body` and LayerPro mounts it with `react-dom`
-`createRoot` inside the modal:
-
-```jsx
-import { useState } from "react";
-
-function Counter() {
-  const [n, setN] = useState(0);
-  return <button onClick={() => setN(n + 1)}>Clicked {n} times</button>;
-}
-
-layerpro.popup.open({
-  id: "reactModal",
-  name: "React Modal",
-  body: <Counter />,
-  width: 400,
-  height: 300
-});
-```
-
-React state, effects, and context all work normally inside the body.
-
----
-
-## Selection & z-index
-
-Clicking anywhere on a popup (the body **or** the title bar) brings it to the
-front and gives it the `zHigh` highlight. The dock icon is also marked as
-selected. z-index values are unitless (set as raw numbers, never `px`).
-
-```javascript
-// Bring a popup to the front programmatically
-layerpro.popup.index({ id: "myModal" });
-```
-
----
-
-## API Methods
-
-| Method | Description |
-|--------|-------------|
-| `layerpro.popup.open(props)` | Open a modal; returns the props. Re-opening a same-id window brings it to front + refreshes body |
-| `layerpro.popup.close(id)` | Close (and unmount) a modal |
-| `layerpro.popup.center(id, offset?)` | Center a modal in the viewport; optional pixel offset |
-| `layerpro.popup.maximize(props)` | Toggle maximize (pure CSS) |
-| `layerpro.popup.iconize(id)` | Toggle minimize to the dock |
-| `layerpro.popup.index(id)` | Bring a modal to the front (select) |
-| `layerpro.popup.zIndex()` | Get the next z-index counter value |
-| `layerpro.popup.movable(props)` | Enable dragging |
-| `layerpro.popup.resizable(props)` | Enable resizing |
-| `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` |
-
----
-
-## Styling & z-index
-
-Popup z-index starts from the `--popup-z-index` CSS variable (default `1000`).
-Apps with their own stacking contexts (e.g. a tooltip at `z-index: 100000`) can
-shift the whole stack by overriding the variable:
-
-```scss
-:root { --popup-z-index: 100000; }
-```
-
-The title bar, window surface, internal area, and body all read from CSS custom
-properties, so theming needs no `!important` and no `[class^=popup_…]` selectors:
-
-| Variable | Applies to |
-|----------|-----------|
-| `--bar-background` | title bar |
-| `--bar-selected-background` | active/selected title bar |
-| `--bar-color` | title bar text |
-| `--window-background` | popup surface |
-| `--window-shadow` | popup shadow |
-| `--window-border-radius` | popup border radius |
-| `--internal-background` | body wrapper |
-| `--body-color` | body text color |
-| `--raised-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
-elements without attribute selectors.
-
----
-
-## Notes & Migration
-
-- **jQuery removed.** LayerPro no longer depends on jQuery. All DOM access uses
-  the internal `core/dom.ts` vanilla helper (`lp`, `lpAll`, `lpCreate`, `lpDoc`,
-  `lpWin`). Public behavior is unchanged.
-- **React is external.** `react` and `react-dom` must be provided by the host
-  app and are used only to render the modal body.
-- **Instant resize / maximize.** Transitions are disabled during resize, and
-  maximize is CSS-only, for a snappy, lag-free feel.
-- **Vanilla pages still work.** No framework is required unless you pass a React
-  body.
-
----
-
-© [Dario Passariello](https://dario.passariello.ca/) — MIT License
+# LayerPro Guide
+
+> 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
+with small, chainable vanilla helpers. React and react-dom are the only
+external runtime dependencies, and they are used **only** to render the modal
+body when you pass a React element.
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+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)
+
+---
+
+## Installation
+
+```bash
+npm install layerpro
+```
+
+Or drop it straight into HTML (UMD build):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/layerpro"></script>
+```
+
+---
+
+## Quick Start
+
+Import LayerPro once at your app entry point. It overrides the global
+`alert`, `confirm`, `prompt`, and exposes `message` and `layerpro`:
+
+```javascript
+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:
+>
+> ```javascript
+> import "layerpro";
+> layerpro.noGlobals();   // restores native alert/confirm/prompt, drops `message`
+> ```
+
+---
+
+## Basic Modals
+
+```javascript
+// Simple alert
+alert("Hello World!");
+
+// Confirm with YES / NO callbacks
+confirm(
+  "Are you sure?",
+  () => console.debug("User clicked YES"),
+  () => console.debug("User clicked NO")
+);
+
+// Prompt with the typed value
+prompt("What is your name?", (name) => {
+  console.debug("User entered:", name);
+});
+
+// Plain message (auto-styled info box)
+message("Operation complete!", () => console.debug("message closed"));
+```
+
+> The global functions keep the same signatures you already know, so legacy
+> code keeps working.
+
+---
+
+## Custom Popups
+
+Use `layerpro.popup.open(props)` for full control.
+
+```javascript
+layerpro.popup.open({
+  id: "myModal",
+  name: "My Modal",
+  body: "<p>Your <b>content</b> here</p>",
+  width: 450,
+  height: 350,
+  movable: true,
+  resizable: true,
+  maximize: true,
+  iconize: true,
+  dockable: true,
+  close: true,
+  buttons: {
+    confirm: { text: "OK", cb: () => layerpro.popup.close("myModal") },
+    cancel: { text: "Cancel", cb: () => layerpro.popup.close("myModal") }
+  }
+});
+```
+
+### The `body` parameter
+
+| Type | Example |
+|------|---------|
+| Plain text | `body: "Hello"` |
+| HTML string | `body: "<p>Hello</p>"` |
+| React element | `body: <MyComponent />` |
+
+> In React, always pass an **element** (`<Component />`), never a call
+> (`Component()`).
+
+---
+
+## Options Reference
+
+```typescript
+{
+  id: string,                 // Unique id (auto-generated as popup_1, popup_2, … if omitted)
+  body: any,                  // text | HTML string | HTMLElement | React element
+  name: string,               // Title shown in the bar
+  icon: string,               // Icon glyph (HTML entity, e.g. "&#9888;") or HTML string
+                              //     (e.g. '<i class="fa fa-star"></i>')
+  class: string,              // Extra CSS class on the window
+
+  // Dimensions (defaults: width 340, height 220; minWidth 340, minHeight 220)
+  width?: number | string,
+  height?: number | string,
+  minWidth?: number,
+  minHeight?: number,
+  maxWidth?: number,
+  maxHeight?: number,
+
+  // Position (numbers are px; strings are applied as-is, e.g. "10%")
+  top?: number | string,
+  left?: number | string,
+  right?: number | string,
+  bottom?: number | string,
+  center?: boolean,           // Center in the viewport (adds a small cascade
+                              //     offset per open window so stacks don't overlap)
+
+  // Timing
+  fadeIn?: number,            // open fade duration (ms, default 100)
+  fadeOut?: number,           // close fade duration (ms, default 100)
+  timer?: number,             // auto-close after N ms
+
+  // Behavior flags
+  movable?: boolean,          // draggable by the title bar
+  resizable?: boolean,        // resize handles
+  maximize?: boolean,         // double-click title bar to maximize
+  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
+}
+```
+
+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.
+
+> **Duplicate id** — opening a popup whose `id` already exists brings that window
+> to the front and refreshes its `body`/`buttons` instead of doing nothing.
+
+---
+
+## Dock & Taskbar
+
+When `dockable` and `iconize` are enabled, a minimized popup becomes an icon in
+the bottom dock bar — exactly like an OS taskbar:
+
+```javascript
+layerpro.popup.open({
+  id: "editor",
+  name: "Editor",
+  body: "<p>Edit something…</p>",
+  dockable: true,
+  iconize: true
+});
+```
+
+**Dock interactions (taskbar style):**
+
+- Click a dock icon of a **minimized** popup → it is restored and focused.
+- Click a dock icon of a popup that is open but **not focused** → it is brought
+  to the front.
+- Click a dock icon of the **focused** popup → it is minimized back to the dock.
+
+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
+resize listeners are involved.
+
+```javascript
+layerpro.popup.open({
+  id: "viewer",
+  name: "Viewer",
+  body: "<p>Big content</p>",
+  maximize: true,
+  iconize: true
+});
+```
+
+- **Double-click the title bar** → toggle maximize / restore.
+- **Click the dock icon** of a maximized popup → restore it.
+
+Because maximize is CSS-driven, resizing the browser window keeps the maximized
+popup perfectly aligned with no lag.
+
+---
+
+## Dragging & Resizing
+
+Dragging and resizing are **instant**: the CSS `transition` is disabled on the
+popup while you drag a resize handle, so the popup tracks the pointer with no
+lag (especially on the bottom edge).
+
+```javascript
+layerpro.popup.open({
+  id: "panel",
+  name: "Panel",
+  body: "<p>Move and resize me</p>",
+  movable: true,
+  resizable: true
+});
+```
+
+- Drag the **title bar** to move.
+- Drag the **edges/corners** to resize.
+- These interactions are disabled automatically while a popup is maximized.
+
+---
+
+## React Body
+
+Pass a React element as `body` and LayerPro mounts it with `react-dom`
+`createRoot` inside the modal:
+
+```jsx
+import { useState } from "react";
+
+function Counter() {
+  const [n, setN] = useState(0);
+  return <button onClick={() => setN(n + 1)}>Clicked {n} times</button>;
+}
+
+layerpro.popup.open({
+  id: "reactModal",
+  name: "React Modal",
+  body: <Counter />,
+  width: 400,
+  height: 300
+});
+```
+
+React state, effects, and context all work normally inside the body.
+
+---
+
+## Selection & z-index
+
+Clicking anywhere on a popup (the body **or** the title bar) brings it to the
+front and gives it the `zHigh` highlight. The dock icon is also marked as
+selected. z-index values are unitless (set as raw numbers, never `px`).
+
+```javascript
+// Bring a popup to the front programmatically
+layerpro.popup.index({ id: "myModal" });
+```
+
+---
+
+## API Methods
+
+| Method | Description |
+|--------|-------------|
+| `layerpro.popup.open(props)` | Open a modal; returns the props. Re-opening a same-id window brings it to front + refreshes body |
+| `layerpro.popup.close(id)` | Close (and unmount) a modal |
+| `layerpro.popup.center(id, offset?)` | Center a modal in the viewport; optional pixel offset |
+| `layerpro.popup.maximize(props)` | Toggle maximize (pure CSS) |
+| `layerpro.popup.iconize(id)` | Toggle minimize to the dock |
+| `layerpro.popup.index(id)` | Bring a modal to the front (select) |
+| `layerpro.popup.zIndex()` | Get the next z-index counter value |
+| `layerpro.popup.movable(props)` | Enable dragging |
+| `layerpro.popup.resizable(props)` | Enable resizing |
+| `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` |
+
+---
+
+## Styling & z-index
+
+Popup z-index starts from the `--popup-z-index` CSS variable (default `1000`).
+Apps with their own stacking contexts (e.g. a tooltip at `z-index: 100000`) can
+shift the whole stack by overriding the variable:
+
+```scss
+:root { --popup-z-index: 100000; }
+```
+
+The title bar, window surface, internal area, and body all read from CSS custom
+properties, so theming needs no `!important` and no `[class^=popup_…]` selectors:
+
+| Variable | Applies to |
+|----------|-----------|
+| `--bar-background` | title bar |
+| `--bar-selected-background` | active/selected title bar |
+| `--bar-color` | title bar text |
+| `--window-background` | popup surface |
+| `--window-shadow` | popup shadow |
+| `--window-border-radius` | popup border radius |
+| `--internal-background` | body wrapper |
+| `--body-color` | body text color |
+| `--raised-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
+elements without attribute selectors.
+
+---
+
+## Notes & Migration
+
+- **jQuery removed.** LayerPro no longer depends on jQuery. All DOM access uses
+  the internal `core/dom.ts` vanilla helper (`lp`, `lpAll`, `lpCreate`, `lpDoc`,
+  `lpWin`). Public behavior is unchanged.
+- **React is external.** `react` and `react-dom` must be provided by the host
+  app and are used only to render the modal body.
+- **Instant resize / maximize.** Transitions are disabled during resize, and
+  maximize is CSS-only, for a snappy, lag-free feel.
+- **Vanilla pages still work.** No framework is required unless you pass a React
+  body.
+
+---
+
+© [Dario Passariello](https://dario.passariello.ca/) — MIT License