@vicaniddouglas/js_aide 1.12.0 → 1.13.1

package/README.md

@@ -1,12 +1,13 @@
 # @vicaniddouglas/js_aide
 
-A versatile collection of modular JavaScript utility helpers designed to streamline single-page application (SPA) development and general web programming tasks. This library provides a set of independent modules for common functionalities such as routing, input handling, validation, and more.
+[![Documentation & Demo](https://img.shields.io/badge/Live-Documentation%20%26%20Demo-blue?style=for-the-badge&logo=gitlab)](https://vicaniddouglas.gitlab.io/js_aide)
 
-## Description
+**JS Aide** is a high-performance, modular utility collection designed for modern web applications. Whether you're building a native SPA or an enterprise-grade MPA, JS Aide provides the orchestrated power you need.
 
-`@vicaniddouglas/js_aide` bundles frequently needed JavaScript functionalities into a cohesive, easy-to-use package. Each module is designed to be independent, allowing you to import only what you need, reducing bundle size and improving application performance. From dynamic client-side routing to robust input validation and DOM manipulation, this library aims to accelerate your development workflow.
-
-## Features
+## 🕹️ Live Playground
+Explore all library features—including the new Asynchronous Handshaking system—directly in our **[Interactive Sandbox](https://vicaniddouglas.gitlab.io/js_aide)**.
+npm explore @vicaniddouglas/js_aide -- npm run serve:demo
+```
 
 ### `Router`
 
@@ -337,6 +338,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;
   };