layerpro 3.0.1 → 3.1.0

package/llms.txt

@@ -11,7 +11,7 @@
 - [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`.
+- [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).
@@ -42,7 +42,7 @@
 - **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; clicking body or title bar selects (brings to front).
+- **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
 

package/markdown/GUIDE.md

@@ -51,7 +51,18 @@ import "layerpro";
 ```
 
 That single import is enough — `window.layerpro` becomes available and the
-global `alert`/`confirm`/`prompt` are replaced.
+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`
+> ```
 
 ---
 
@@ -123,13 +134,14 @@ layerpro.popup.open({
 
 ```typescript
 {
-  id: string,                 // Unique id (required)
+  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
+  icon: string,               // Icon glyph (HTML entity, e.g. "⚠") or HTML string
+                              //     (e.g. '<i class="fa fa-star"></i>')
   class: string,              // Extra CSS class on the window
 
-  // Dimensions
+  // Dimensions (defaults: width 340, height 220; minWidth 340, minHeight 220)
   width?: number | string,
   height?: number | string,
   minWidth?: number,
@@ -142,10 +154,12 @@ layerpro.popup.open({
   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)
-  fadeOut?: number,           // close fade duration (ms)
+  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
@@ -154,18 +168,21 @@ layerpro.popup.open({
   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,           // start raised / focused
-
-  // Buttons
-  buttons?: {
-    confirm?: { text: string; cb?: () => void },
-    cancel?:  { text: string; cb?: () => void }
-  }
+  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.
+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.
 
 ---
 
@@ -284,17 +301,52 @@ layerpro.popup.index({ id: "myModal" });
 
 | Method | Description |
 |--------|-------------|
-| `layerpro.popup.open(props)` | Open a modal; returns the props |
+| `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)` | Center a modal in the viewport |
-| `layerpro.popup.maximize(id)` | Toggle maximize (pure CSS) |
+| `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(id)` | Enable dragging |
-| `layerpro.popup.resizable(id)` | Enable resizing |
+| `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.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "layerpro",
   "codeName": "layerpro",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "The real custom modals, alert, confirm, prompt... for your browser",
   "main": "./index.cjs",
   "browser": "./index.js",

package/types/layerpro.d.ts

@@ -4,16 +4,21 @@
 /// <reference types="react" />
 
 /** Generate custom alert using alert([text]) */
-declare function alert(f1?: string): any
+declare function alert(f1?: string): void
 
-/** Generate custom confirm using confirm([text],[callback for YES],[optional callback for NO]) */
-declare function confirm(message: string, func1: Function, func2?: Function): boolean
+/** 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?: Function): any
+declare function message(f1?: string, func1?: () => void): void
 
-/** Generate custom message using message([text],[callback]) and option callback */
-declare function prompt(f1?: string, func1?: Function): any
+/** 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
 
 ///
 
@@ -62,7 +67,9 @@ interface GenLayerProps {
   resizable?: boolean
   close?: boolean
   raised?: boolean
+  modal?: boolean
   iconize?: boolean
+  center?: boolean
 
   source?: string
   store?: any
@@ -77,26 +84,29 @@ interface _layerpro {
   [key: string]: any
 
   readonly alert: (txt: string) => void
-  readonly prompt: (txt: string, callback: (input: string) => void, event: Event) => 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 confirm: (txt: string, yesCallback: () => void, noCallback?: () => void) => void
   readonly credits: (txt: string) => void
 
-  setProps: (obj, options?) => 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
 
   readonly popup: {
     open: (props: GenLayerProps) => GenLayerProps
-    center: (props: any) => void
-    maximize: (props: any) => void
-    iconize: (props: any) => void
-    raised: (props: any) => void
-    movable: (props: any) => void
-    resizable: (props: any) => void
-    dockable: (props: any) => void
-    store: (props: any) => void
-    index: (props: any) => void
-    zIndex: (props?: any) => number
-    close: (props: any) => any
+    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) => void
     // React root management for memory cleanup
     unmount: (id: string) => void
     getReactRoot: (id: string) => any
@@ -106,12 +116,13 @@ interface _layerpro {
 
 }
 
+/**
+ * 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.
+ */
 interface Window {
-  [key: string]: any
-}
-
-interface globalThis {
-  [key: string]: any
+  layerpro: _layerpro
 }
 
 declare var layerpro: _layerpro