docs: note MacroAbortError on prompt cancellation

Author: chhoumann

docs/docs/Advanced/onePageInputs.md

@@ -184,3 +184,4 @@ Behavior:
 - Preflight may import user script modules to statically read `quickadd.inputs`. This can execute module top-level code.
 - Inline scripts aren’t scanned for input declarations yet.
 - If needed, you can still prompt ad-hoc (e.g., using inputPrompt or suggester) and those values will skip future one-page prompts due to being prefilled.
+- Closing the modal without submitting triggers `MacroAbortError("Input cancelled by user")`, which stops the macro unless you catch it.

docs/docs/QuickAddAPI.md

@@ -38,6 +38,7 @@ Opens a one-page modal to collect multiple inputs in one go. Values already pres
 **Behavior:**
 - Uses existing values for any ids that already exist in `variables` (including empty strings).
 - Prompts only for missing (`undefined`/`null`) inputs.
+- If the user closes the modal without submitting, the promise rejects with `MacroAbortError("Input cancelled by user")`.
 
 **Field Types:**
 - `text`: Single-line text input
@@ -115,18 +116,25 @@ Opens a prompt that asks for text input.
 - `placeholder`: (Optional) Placeholder text in the input field
 - `value`: (Optional) Default value
 
-**Returns:** Promise resolving to the entered string, or `null` if cancelled
+**Returns:** Promise resolving to the entered string.
+
+**Cancellation:** If the user cancels or presses Escape, the promise rejects with `MacroAbortError("Input cancelled by user")`. Letting it bubble will stop the macro automatically. Catch it only if your script wants to handle the cancellation itself.
 
 **Example:**
 ```javascript
-const name = await quickAddApi.inputPrompt(
-    "What's your name?",
-    "Enter your full name",
-    "John Doe"
-);
-
-if (name) {
-    console.log(`Hello, ${name}!`);
+try {
+	const name = await quickAddApi.inputPrompt(
+		"What's your name?",
+		"Enter your full name",
+		"John Doe"
+	);
+	console.log(`Hello, ${name}!`);
+} catch (error) {
+	if (error?.name === "MacroAbortError") {
+		// Optional: perform cleanup before QuickAdd aborts the macro
+		return;
+	}
+	throw error;
 }
 ```
 
@@ -135,7 +143,7 @@ Opens a wider prompt for longer text input (multi-line).
 
 **Parameters:** Same as `inputPrompt`
 
-**Returns:** Promise resolving to the entered string, or `null` if cancelled
+**Returns:** Promise resolving to the entered string. Cancelling rejects with `MacroAbortError` (same as `inputPrompt`).
 
 **Example:**
 ```javascript
@@ -153,7 +161,7 @@ Opens a confirmation dialog with Yes/No buttons.
 - `header`: The dialog title
 - `text`: (Optional) Additional explanation text
 
-**Returns:** Promise resolving to `true` (Yes) or `false` (No)
+**Returns:** Promise resolving to `true` (Yes) or `false` (No). If the user closes the dialog without answering, the promise rejects with `MacroAbortError`.
 
 **Example:**
 ```javascript
@@ -196,7 +204,7 @@ Opens a selection prompt with searchable options. Can optionally allow custom in
 - `allowCustomInput`: (Optional) When `true`, allows users to enter custom text not in `actualItems`. Defaults to `false`
 - `options.renderItem`: (Optional) Custom renderer `(value, el) => void` to control how each suggestion row is drawn
 
-**Returns:** Promise resolving to the selected value or custom input, or `null` if cancelled
+**Returns:** Promise resolving to the selected value or custom input. Cancelling rejects with `MacroAbortError`.
 
 **Examples:**
 

docs/docs/UserScripts.md

@@ -297,27 +297,44 @@ module.exports = async (params) => {
 - No error is thrown to the user
 
 **QuickAdd API methods that can be cancelled:**
-- `inputPrompt()` - Returns `undefined` if cancelled
-- `wideInputPrompt()` - Returns `undefined` if cancelled
-- `yesNoPrompt()` - Returns `undefined` if cancelled
-- `suggester()` - Aborts macro if cancelled
-- `checkboxPrompt()` - Returns `undefined` if cancelled
+- `inputPrompt()`
+- `wideInputPrompt()`
+- `yesNoPrompt()`
+- `suggester()`
+- `checkboxPrompt()`
 
-**Important:** When using the QuickAdd API, check for `undefined` to handle cancellations gracefully:
+Each of these now rejects with `MacroAbortError("Input cancelled by user")` when the user presses Escape or closes the dialog. If you do nothing, the macro will automatically stop (matching user expectations). If you want to handle cancellation in your script, wrap the call in `try/catch` and intercept the error before it reaches the macro engine.
+
+```javascript
+try {
+	const name = await quickAddApi.inputPrompt("Your name:");
+} catch (error) {
+	if (error?.name === "MacroAbortError") {
+		// Optional custom handling (e.g., cleanup) before the macro aborts
+		return;
+	}
+	throw error; // real errors should still bubble up
+}
+```
+
+**Important:** Because cancellations now throw, you should only call `abort()` yourself when you want to provide a custom message or stop execution for a non-prompt reason.
 
 ```javascript
 module.exports = async (params) => {
-    const { quickAddApi, abort } = params;
-    
-    const name = await quickAddApi.inputPrompt("Your name:");
-    
-    // Handle cancellation
-    if (!name) {
-        abort("Name is required");
-    }
-    
-    // Safe to use name here
-    console.log(`Processing: ${name}`);
+	const { quickAddApi, abort } = params;
+	
+	let name;
+	try {
+		name = await quickAddApi.inputPrompt("Your name:");
+	} catch (error) {
+		if (error?.name === "MacroAbortError") {
+			abort("Name is required");
+			return;
+		}
+		throw error;
+	}
+	
+	console.log(`Processing: ${name}`);
 };
 ```
 
@@ -906,4 +923,4 @@ For complete working examples, see:
 **API methods returning undefined:**
 - Ensure you're using `await` with async methods
 - Check that QuickAdd plugin is enabled
-- Verify you're accessing the API correctly through `params.quickAddApi`
+- Verify you're accessing the API correctly through `params.quickAddApi`