@vicaniddouglas/js_aide 1.12.0 → 1.13.0

package/README.md

@@ -8,6 +8,19 @@ A versatile collection of modular JavaScript utility helpers designed to streaml
 
 ## Features
 
+### 🎮 Live Playground
+Explore all library features—including the new Asynchronous Handshaking system—directly in our interactive sandbox.
+
+**Access via Repository:**
+1. Clone the repository: `git clone https://gitlab.com/vicaniddouglas/js_aide.git`
+2. Open `demo/index.html` in any modern browser.
+
+**Access via NPM:**
+If you have the package installed locally, you can run the playground using:
+```bash
+npm explore @vicaniddouglas/js_aide -- npm run serve:demo
+```
+
 ### `Router`
 
 A modern, feature-rich client-side router for Single-Page Applications (SPAs).
@@ -337,6 +350,40 @@ popup.success("Photo Uploaded!", {
 });
 ```
 
+#### 4. Asynchronous Handshaking (Zero-Alert)
+The popup system provides replacements for native `confirm()` and `prompt()` that are fully asynchronous, themeable, and non-blocking in the developer's logic (via `await`).
+
+**Confirmation Dialogs**
+Returns `true` on confirm, `false` on cancel/close.
+```javascript
+const confirmed = await popup.confirm("Are you sure you want to delete this?");
+
+if (confirmed) {
+  await deleteRecord();
+  await popup.success("Deleted!");
+}
+```
+
+**Data-Entry Prompts**
+Returns the input value as a **string** on submit, or `null` if cancelled.
+```javascript
+const name = await popup.prompt("Enter your display name:", {
+  placeholder: "e.g., Douglas",
+  inputType: "text" // Options: text, number, currency, password
+});
+
+if (name) {
+  console.log("Hello", name);
+}
+```
+
+| Prompt Option | Description |
+| :--- | :--- |
+| `inputType` | Controls input behavior (`text`, `number`, `currency`, `password`). |
+| `defaultValue`| Initial text inside the input. |
+| `submitText` | Text for the action button (default: "Submit"). |
+| `cancelText` | Text for the dismiss button (default: "Cancel"). |
+
 ## Development
 
 ### Running Tests

package/declarations.d.ts

@@ -1250,6 +1250,26 @@ declare module "@vicaniddouglas/js_aide" {
     color?: string;
   }
 
+  interface ConfirmOptions extends PopupOptions {
+    /** Text for the confirm button (default: "Confirm") */
+    confirmText?: string;
+    /** Text for the cancel button (default: "Cancel") */
+    cancelText?: string;
+  }
+
+  interface PromptOptions extends PopupOptions {
+    /** Type of input: text, number, currency, or password */
+    inputType?: "text" | "number" | "currency" | "password";
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Initial value for the input */
+    defaultValue?: string;
+    /** Text for the submit button (default: "Submit") */
+    submitText?: string;
+    /** Text for the cancel button (default: "Cancel") */
+    cancelText?: string;
+  }
+
   export const popup: {
     /** Show a success modal (Green theme) */
     success(message: string, options?: PopupOptions): Promise<void>;
@@ -1257,6 +1277,10 @@ declare module "@vicaniddouglas/js_aide" {
     error(message: string, options?: PopupOptions): Promise<void>;
     /** Show an info modal (Blue theme) */
     info(message: string, options?: PopupOptions): Promise<void>;
+    /** Show a confirmation dialog (Slate theme). Returns true if confirmed, false otherwise. */
+    confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
+    /** Show a prompt dialog (Slate theme). Returns the value if submitted, null if cancelled. */
+    prompt(message: string, options?: PromptOptions): Promise<string | null>;
     /** Programmatically close the current modal */
     close(): void;
   };