@vicaniddouglas/js_aide 1.11.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).
@@ -230,13 +243,32 @@ Every call returns a Promise that always resolves to this structure:
 #### New Proactive Options
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `onSuccess` | `Function` | `null` | Runs automatically if `status` is `true`. |
-| `onError` | `Function` | `null` | Runs automatically if `status` is `false`. |
+| `onSuccess` | `Function` | `null` | Runs automatically if `status` is `true`. **Strictly awaited.** |
+| `onError` | `Function` | `null` | Runs automatically if `status` is `false`. **Strictly awaited.** |
+| `showLoading` | `Function` | `null` | Called with `true`/`false`. **Strictly awaited.** |
 | `silent` | `Boolean` | `false` | If `true`, disables the automatic Red Popup on error. |
 
 #### Usage Patterns
 
-**1. The "Fire and Forget" (Proactive Success)**
+**1. The "Sequential Async Flow" (Awaiting Callbacks)**
+Because `sendRequest` **strictly awaits** your callbacks, you can safely use `async/await` inside them without worrying about race conditions or premature page reloads.
+```javascript
+import { sendRequest, popup } from "@vicaniddouglas/js_aide";
+
+await sendRequest({
+  endpoint: '/api/save',
+  onSuccess: async (data) => {
+    // This popup is BEAUTIFUL and BLOCKING.
+    // sendRequest will NOT finish until the user clicks OK.
+    await popup.success("Settings Saved!"); 
+  }
+});
+
+// This reload is GUARANTEED to happen only after the popup is closed.
+window.location.reload(); 
+```
+
+**2. The "Fire and Forget" (Proactive Success)**
 No need to check status if you only care about success. If it fails, the user gets a popup automatically.
 ```javascript
 import { sendRequest } from "@vicaniddouglas/js_aide";
@@ -318,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

@@ -313,7 +313,10 @@ declare module "@vicaniddouglas/js_aide" {
     useQueue?: boolean;
     priority?: number;
     responseType?: "json" | "text";
-    showLoading?: (isLoading: boolean) => void;
+    showLoading?: (isLoading: boolean) => void | Promise<void>;
+    onSuccess?: (data: any) => void | Promise<void>;
+    onError?: (log: string) => void | Promise<void>;
+    silent?: boolean;
   }
 
   type RequestInterceptor = (
@@ -1247,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>;
@@ -1254,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;
   };