feat: improve prompt labeling for VALUE/MACRO and multi choices

* feat: add labels and placeholders for prompts

* feat: use option syntax for VALUE labels

* docs: clarify VALUE option default syntax

* refactor: use sentinel delimiter for VALUE label keys

* test: key VALUE label requirements via parser

* refactor: share VALUE label key helper

* refactor: centralize VALUE key handling

* test: add valueSyntax coverage

* feat: add label option to macro syntax

* fix: require label option for macro labels

Author: chhoumann

docs/docs/Choices/MultiChoice.md

@@ -9,3 +9,7 @@ Multi-choices are pretty simple. They're like folders for other choices. Here ar
 To actually add something in this "folder", you need to drag it in! This is not easy to do when it is the first item in the multi-folder.
 
 Make sure the multi is unfolded (as it is in the screenshot). Click the drag handle of one of the choices you want to add and drag it to just below and to the right of the drag handle for the multi. When successful, the choice will be indented under the multi.
+
+## Placeholder text
+
+You can optionally set a placeholder for each Multi choice. This text shows up in the choice picker search box when you open the multi, which is handy for complex menus or grouped workflows. Leave it empty to keep the default placeholder.

docs/docs/FormatSyntax.md

@@ -10,11 +10,14 @@ title: Format syntax
 | `{{VDATE:<variable name>, <date format>\|<default>}}` | Same as above, but with a default value. If you leave the prompt empty, the default value will be used instead. Example: `{{VDATE:date,YYYY-MM-DD\|today}}` will use "today" if no input is provided. Default values can be any natural language date like "tomorrow", "next monday", "+7 days", etc. Short aliases like `t`, `tm`, and `yd` work here too. **Note:** If your date format contains pipe characters (`|`), you'll need to escape them as `\|` or use square brackets like `[|]` to avoid conflicts with the default value separator. |
 | `{{VALUE}}` or `{{NAME}}`                  | Interchangeable. Represents the value given in an input prompt. If text is selected in the current editor, it will be used as the value. When using the QuickAdd API, this can be passed programmatically using the reserved variable name 'value'.                                                                                                                                             |
 | `{{VALUE:<variable name>}}`                  | You can now use variable names in values. They'll get saved and inserted just like values, but the difference is that you can have as many of them as you want. Use comma separation to get a suggester rather than a prompt.                                                       |
-| `{{VALUE:<variable name>\|<default>}}`        | Same as above, but with a default value. For single-value prompts (e.g., `{{VALUE:name\|Anonymous}}`), the default is pre-populated in the input field - press Enter to accept or clear/edit it. For multi-value suggesters without `\|custom`, you must select one of the provided options (no default applies).                                                                                  |
-| `{{VALUE:<options>\|custom}}`        | Allows you to type custom values in addition to selecting from the provided options. Example: `{{VALUE:Red,Green,Blue\|custom}}` will suggest Red, Green, and Blue, but also allows you to type any other value like "Purple". This is useful when you have common options but want flexibility for edge cases. **Note:** You cannot combine `\|custom` with a default value - it's either one or the other.                                                                                  |
+| `{{VALUE:<variable name>\|label:<helper text>}}`     | Adds helper text to the prompt for a single-value input. The helper appears below the header and is useful for reminders or instructions. For multi-value lists, use the same syntax to label the suggester (e.g., `{{VALUE:Red,Green,Blue\|label:Pick a color}}`). |
+| `{{VALUE:<variable name>\|<default>}}`        | Same as above, but with a default value. For single-value prompts (e.g., `{{VALUE:name\|Anonymous}}`), the default is pre-populated in the input field - press Enter to accept or clear/edit it. For multi-value suggesters without `\|custom`, you must select one of the provided options (no default applies). If you combine options like `\|label:...`, use `\|default:<value>` instead of the shorthand (mixing option keys with a bare default is not supported). |
+| `{{VALUE:<variable name>\|default:<value>}}`        | Option-form default value, required when combining with other options like `\|label:`. Example: `{{VALUE:title\|label:Snake case\|default:My_Title}}`. |
+| `{{VALUE:<options>\|custom}}`        | Allows you to type custom values in addition to selecting from the provided options. Example: `{{VALUE:Red,Green,Blue\|custom}}` will suggest Red, Green, and Blue, but also allows you to type any other value like "Purple". This is useful when you have common options but want flexibility for edge cases. **Note:** You cannot combine `\|custom` with a shorthand default value - use `\|default:` if you need both. |
 | `{{LINKCURRENT}}`                          | A link to the file from which the template or capture was triggered (`[[link]]` format). When the append-link setting is set to **Enabled (skip if no active file)**, this token resolves to an empty string instead of throwing an error if no note is focused. |
 | `{{FILENAMECURRENT}}`                      | The basename (without extension) of the file from which the template or capture was triggered. Honors the same **required/optional** behavior as `{{LINKCURRENT}}` - when optional and no active file exists, resolves to an empty string. |
 | `{{MACRO:<MACRONAME>}}`                    | Execute a macro and write the return value here.                                                                                                                                                                                                                            |
+| `{{MACRO:<MACRONAME>\|label:<label>}}`           | Executes the macro but shows the label as the placeholder when the macro prompts you to choose an export from a script object. This is helpful when multiple macro calls show similar lists. |
 | `{{TEMPLATE:<TEMPLATEPATH>}}`              | Include templates in your `format`. Supports Templater syntax.                                                                                                                                                                                                                                                                                    |
 | `{{GLOBAL_VAR:<name>}}`                    | Inserts the value of a globally defined snippet from QuickAdd settings. Snippet values can include other QuickAdd tokens (e.g., `{{VALUE:...}}`, `{{VDATE:...}}`) and are processed by the usual formatter passes. Names match case‑insensitively in the token. |
 | `{{MVALUE}}`                               | Math modal for writing LaTeX. Use CTRL + Enter to submit. |                                                                                                                                                                                                                                                                         

src/choiceExecutor.ts

@@ -33,13 +33,24 @@ export class ChoiceExecutor implements IChoiceExecutor {
 
 	async execute(choice: IChoice): Promise<void> {
 		this.pendingAbort = null;
-    // One-page preflight honoring per-choice override
-    const globalEnabled = settingsStore.getState().onePageInputEnabled;
-    const override = choice.onePageInput;
-    const shouldUseOnePager = (override === "always") || (override !== "never" && globalEnabled);
-    if (shouldUseOnePager && (choice.type === "Template" || choice.type === "Capture" || choice.type === "Macro")) {
+		// One-page preflight honoring per-choice override.
+		const globalEnabled = settingsStore.getState().onePageInputEnabled;
+		const override = choice.onePageInput;
+		const shouldUseOnePager =
+			override === "always" || (override !== "never" && globalEnabled);
+		if (
+			shouldUseOnePager &&
+			(choice.type === "Template" ||
+				choice.type === "Capture" ||
+				choice.type === "Macro")
+		) {
 			try {
-				await runOnePagePreflight(this.app, this.plugin as unknown as QuickAdd, this, choice);
+				await runOnePagePreflight(
+					this.app,
+					this.plugin as unknown as QuickAdd,
+					this,
+					choice,
+				);
 			} catch (error) {
 				if (isCancellationError(error)) {
 					throw new MacroAbortError("One-page input cancelled by user");
@@ -111,6 +122,9 @@ export class ChoiceExecutor implements IChoiceExecutor {
 	}
 
 	private onChooseMultiType(multiChoice: IMultiChoice) {
-		ChoiceSuggester.Open(this.plugin, multiChoice.choices, this);
+		ChoiceSuggester.Open(this.plugin, multiChoice.choices, {
+			choiceExecutor: this,
+			placeholder: multiChoice.placeholder,
+		});
 	}
 }

src/constants.ts

@@ -5,6 +5,10 @@ export const NAME_SYNTAX = "{{name}}";
 export const VARIABLE_SYNTAX = "{{value:<variable name>}}";
 export const VARIABLE_DEFAULT_SYNTAX =
 	"{{value:<variable name>|<default value>}}";
+export const VARIABLE_DEFAULT_OPTION_SYNTAX =
+	"{{value:<variable name>|default:<value>}}";
+export const VARIABLE_LABEL_SYNTAX =
+	"{{value:<variable name>|label:<helper text>}}";
 export const FIELD_VAR_SYNTAX = "{{field:<field name>}}";
 export const MATH_VALUE_SYNTAX = "{{mvalue}}";
 export const LINKCURRENT_SYNTAX = "{{linkcurrent}}";
@@ -25,13 +29,16 @@ export const FORMAT_SYNTAX: string[] = [
 	NAME_SYNTAX,
 	VARIABLE_SYNTAX,
 	VARIABLE_DEFAULT_SYNTAX,
+	VARIABLE_DEFAULT_OPTION_SYNTAX,
+	VARIABLE_LABEL_SYNTAX,
 	FIELD_VAR_SYNTAX,
 	"{{field:<fieldname>|folder:<path>}}",
 	"{{field:<fieldname>|tag:<tagname>}}",
 	"{{field:<fieldname>|inline:true}}",
 	LINKCURRENT_SYNTAX,
 	FILENAMECURRENT_SYNTAX,
 	"{{macro:<macroname>}}",
+	"{{macro:<macroname>|label:<label>}}",
 	"{{template:<templatepath>}}",
 	MATH_VALUE_SYNTAX,
 	SELECTED_SYNTAX,
@@ -49,6 +56,8 @@ export const FILE_NAME_FORMAT_SYNTAX: string[] = [
 	NAME_SYNTAX,
 	VARIABLE_SYNTAX,
 	VARIABLE_DEFAULT_SYNTAX,
+	VARIABLE_DEFAULT_OPTION_SYNTAX,
+	VARIABLE_LABEL_SYNTAX,
 	FIELD_VAR_SYNTAX,
 	RANDOM_SYNTAX,
 ];

src/engine/MacroChoiceEngine.ts

@@ -79,6 +79,7 @@ export class MacroChoiceEngine extends QuickAddChoiceEngine {
 	private userScriptCommand: IUserScript | null;
 	private conditionalScriptCache = new Map<string, ConditionalScriptRunner>();
 	private readonly preloadedUserScripts: Map<string, unknown>;
+	private readonly promptLabel?: string;
 	private buildParams(
 		app: App,
 		plugin: QuickAdd,
@@ -151,14 +152,16 @@ export class MacroChoiceEngine extends QuickAddChoiceEngine {
 		choice: IMacroChoice,
 		choiceExecutor: IChoiceExecutor,
 		variables: Map<string, unknown>,
-		preloadedUserScripts?: Map<string, unknown>
+		preloadedUserScripts?: Map<string, unknown>,
+		promptLabel?: string,
 	) {
 		super(app);
 		this.choice = choice;
 		this.plugin = plugin;
 		this.macro = choice?.macro;
 		this.choiceExecutor = choiceExecutor;
 		this.preloadedUserScripts = preloadedUserScripts ?? new Map();
+		this.promptLabel = promptLabel;
 		const sharedVariables = this.initSharedVariables(
 			choiceExecutor,
 			variables
@@ -372,7 +375,8 @@ export class MacroChoiceEngine extends QuickAddChoiceEngine {
 			const selected: string = await GenericSuggester.Suggest(
 				this.app,
 				keys,
-				keys
+				keys,
+				this.promptLabel,
 			);
 
 			await this.userScriptDelegator(obj[selected]);

src/engine/SingleMacroEngine.ts

@@ -42,7 +42,10 @@ export class SingleMacroEngine {
 		}
 	}
 
-	public async runAndGetOutput(macroName: string): Promise<string> {
+	public async runAndGetOutput(
+		macroName: string,
+		context?: { label?: string },
+	): Promise<string> {
 		const { basename, memberAccess } = getUserScriptMemberAccess(macroName);
 
 		// ------------------------------------------------------------------
@@ -94,6 +97,7 @@ export class SingleMacroEngine {
 			this.choiceExecutor,
 			this.variables,
 			preloadedScripts,
+			context?.label,
 		);
 
 		if (memberAccess?.length) {

src/formatters/completeFormatter.ts

@@ -24,7 +24,7 @@ import {
 	generateFieldCacheKey,
 } from "../utils/FieldValueCollector";
 import { FieldValueProcessor } from "../utils/FieldValueProcessor";
-import { Formatter } from "./formatter";
+import { Formatter, type PromptContext } from "./formatter";
 import { MacroAbortError } from "../errors/MacroAbortError";
 import { isCancellationError } from "../utils/errorUtils";
 
@@ -192,14 +192,14 @@ export class CompleteFormatter extends Formatter {
 
 	protected async promptForVariable(
 		header?: string,
-		context?: { type?: string; dateFormat?: string; defaultValue?: string },
+		context?: PromptContext,
 	): Promise<string> {
 		try {
 			// Use VDateInputPrompt for VDATE variables
 			if (context?.type === "VDATE" && context.dateFormat) {
 				return await VDateInputPrompt.Prompt(
 					this.app,
-					header as string,
+					(header as string) ?? context.label ?? "Enter date",
 					"Enter a date (e.g., 'tomorrow', 'next friday', '2025-12-25')",
 					context.defaultValue,
 					context.dateFormat,
@@ -208,11 +208,13 @@ export class CompleteFormatter extends Formatter {
 
 			// Use default prompt for other variables
 			return await new InputPrompt().factory().Prompt(
-			this.app,
-			header as string,
-			context?.defaultValue ? context.defaultValue : undefined,
-			context?.defaultValue
-		);
+				this.app,
+				header ?? context?.label ?? "Enter value",
+				context?.placeholder ??
+					(context?.defaultValue ? context.defaultValue : undefined),
+				context?.defaultValue,
+				context?.description,
+			);
 		} catch (error) {
 			if (isCancellationError(error)) {
 				throw new MacroAbortError("Input cancelled by user");
@@ -232,19 +234,29 @@ export class CompleteFormatter extends Formatter {
 		}
 	}
 
-	protected async suggestForValue(suggestedValues: string[], allowCustomInput = false) {
+	protected async suggestForValue(
+		suggestedValues: string[],
+		allowCustomInput = false,
+		context?: { placeholder?: string; variableKey?: string },
+	) {
 		try {
 			if (allowCustomInput) {
 				return await InputSuggester.Suggest(
 					this.app,
 					suggestedValues,
 					suggestedValues,
+					{
+						...(context?.placeholder
+							? { placeholder: context.placeholder }
+							: {}),
+					},
 				);
 			}
 			return await GenericSuggester.Suggest(
 				this.app,
 				suggestedValues,
 				suggestedValues,
+				context?.placeholder,
 			);
 		} catch (error) {
 			if (isCancellationError(error)) {
@@ -308,7 +320,10 @@ export class CompleteFormatter extends Formatter {
 		return generateFieldCacheKey(filters);
 	}
 
-	protected async getMacroValue(macroName: string): Promise<string> {
+	protected async getMacroValue(
+		macroName: string,
+		context?: { label?: string },
+	): Promise<string> {
 		const macroEngine: SingleMacroEngine = new SingleMacroEngine(
 			this.app,
 			this.plugin,
@@ -317,7 +332,8 @@ export class CompleteFormatter extends Formatter {
 			this.choiceExecutor,
 			this.variables,
 		);
-		const macroOutput = (await macroEngine.runAndGetOutput(macroName)) ?? "";
+		const macroOutput =
+			(await macroEngine.runAndGetOutput(macroName, context)) ?? "";
 
 		// Copy variables from macro execution
 		macroEngine.getVariables().forEach((value, key) => {

src/formatters/fileNameDisplayFormatter.ts

@@ -1,4 +1,4 @@
-import { Formatter } from "./formatter";
+import { Formatter, type PromptContext } from "./formatter";
 import type { App } from "obsidian";
 import { DATE_VARIABLE_REGEX, GLOBAL_VAR_REGEX } from "../constants";
 import type { IDateParser } from "../parsers/IDateParser";
@@ -12,6 +12,7 @@ import {
 	getCurrentFileNamePreview,
 	DateFormatPreviewGenerator
 } from "./helpers/previewHelpers";
+import { getValueVariableBaseName } from "../utils/valueSyntax";
 
 import type QuickAdd from "../main";
 
@@ -71,7 +72,10 @@ export class FileNameDisplayFormatter extends Formatter {
 	}
 
 	protected getVariableValue(variableName: string): string {
-		return getVariableExample(variableName);
+		const stored = this.variables.get(variableName);
+		if (typeof stored === "string") return stored;
+		const baseName = getValueVariableBaseName(variableName);
+		return getVariableExample(baseName);
 	}
 
 	protected getCurrentFileLink(): string | null {
@@ -84,21 +88,28 @@ export class FileNameDisplayFormatter extends Formatter {
 		return getCurrentFileNamePreview(this.app.workspace.getActiveFile());
 	}
 
-	protected suggestForValue(suggestedValues: string[], allowCustomInput = false) {
+	protected suggestForValue(
+		suggestedValues: string[],
+		allowCustomInput = false,
+		_context?: { placeholder?: string; variableKey?: string },
+	) {
 		return getSuggestionPreview(suggestedValues);
 	}
 
 	protected promptForMathValue(): Promise<string> {
 		return Promise.resolve("calculation_result");
 	}
 
-	protected getMacroValue(macroName: string) {
+	protected getMacroValue(
+		macroName: string,
+		_context?: { label?: string },
+	) {
 		return getMacroPreview(macroName);
 	}
 
 	protected async promptForVariable(
 		variableName: string,
-		context?: { type?: string; dateFormat?: string }
+		context?: PromptContext
 	): Promise<string> {
 		return getVariablePromptExample(variableName);
 	}

src/formatters/formatDisplayFormatter.ts

@@ -1,4 +1,4 @@
-import { Formatter } from "./formatter";
+import { Formatter, type PromptContext } from "./formatter";
 import type { App } from "obsidian";
 import type QuickAdd from "../main";
 import { SingleTemplateEngine } from "../engine/SingleTemplateEngine";
@@ -14,6 +14,7 @@ import {
 	getCurrentFileNamePreview,
 	DateFormatPreviewGenerator
 } from "./helpers/previewHelpers";
+import { getValueVariableBaseName } from "../utils/valueSyntax";
 
 export class FormatDisplayFormatter extends Formatter {
 	constructor(
@@ -74,7 +75,10 @@ export class FormatDisplayFormatter extends Formatter {
 	}
 
 	protected getVariableValue(variableName: string): string {
-		return getVariableExample(variableName);
+		const stored = this.variables.get(variableName);
+		if (typeof stored === "string") return stored;
+		const baseName = getValueVariableBaseName(variableName);
+		return getVariableExample(baseName);
 	}
 
 	protected getCurrentFileLink(): string | null {
@@ -87,11 +91,18 @@ export class FormatDisplayFormatter extends Formatter {
 		return getCurrentFileNamePreview(this.app.workspace.getActiveFile());
 	}
 
-	protected suggestForValue(suggestedValues: string[], allowCustomInput = false) {
+	protected suggestForValue(
+		suggestedValues: string[],
+		allowCustomInput = false,
+		_context?: { placeholder?: string; variableKey?: string },
+	) {
 		return getSuggestionPreview(suggestedValues);
 	}
 
-	protected getMacroValue(macroName: string) {
+	protected getMacroValue(
+		macroName: string,
+		_context?: { label?: string },
+	) {
 		return getMacroPreview(macroName);
 	}
 
@@ -101,7 +112,7 @@ export class FormatDisplayFormatter extends Formatter {
 
 	protected promptForVariable(
 		variableName: string,
-		context?: { type?: string; dateFormat?: string; defaultValue?: string }
+		context?: PromptContext
 	): Promise<string> {
 		return Promise.resolve(getVariablePromptExample(variableName));
 	}