Macros 2.0 - Optional scoped content + improved closing-tag autocomplete (#5117) * feat(macros): Add optional scope detection and improved closing tag autocomplete - Implement `isScopeOptional()` to detect when scoped content is optional based on macro argument requirements - Filter optional scopes from autocomplete hints unless force-triggered (Ctrl+Space) - Add "OPTIONAL" badge styling for optional scoped content in autocomplete UI - Show multiple closing tag suggestions (innermost to outermost) with priority ordering - Display nesting level information for nested optional scopes * fix(autocomplete): show original macro details when typing closing tags Add nameOffset=2 to MacroClosingTagAutoCompleteOption to skip {{ prefix for fuzzy highlighting. When typing closing tags ({{/macroName}}), detect and show the original macro's details instead of "no match" error by looking up the macro definition and creating a non-selectable context option with no argument highlighting.

9f4449973b0207955fa057018f668a7f7e0dc8ce

Wolfsblvt <wolfsblvt@gmail.com>

Signed

Parents: 788ed3d32371da7ebd683e7019caa6c890c6b0a4

public/css/macros.css+22 -0 Viewed

     border-radius: 3px;
+}
+/* OPTIONAL badge for optional scoped content */
+.macro-ac-optional-badge {
+    display: inline-block;
+    background: linear-gradient(135deg, #f0ad4e, #ec971f);
+    color: #000;
+    font-weight: bold;
+    font-size: 0.75em;
+    padding: 0.15em 0.5em;
+    border-radius: 3px;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
+}
+/* Smaller variant for use in autocomplete list items */
+.macro-ac-optional-badge-small {
+    font-size: 0.65em;
+    padding: 0.1em 0.35em;
+    vertical-align: middle;
+    color: #f0ad4e;
+}
 /* Closing tag autocomplete option */
 .autoComplete > .item.macro-closing-tag-item > .type {
     color: var(--ac-color-matchedText, var(--SmartThemeBorderColor));

public/scripts/autocomplete/EnhancedMacroAutoCompleteOption.js+54 -1 Viewed

  * @property {boolean} hasSpaceArgContent - Whether there's actual content after the space (not just whitespace).
  * @property {number} separatorCount - Number of '::' separators found.
  * @property {boolean} [isInScopedContent] - Whether cursor is in scoped content (after }} but before closing tag).
+ * @property {boolean} [isScopedContentOptional] - Whether the scoped content is optional (for display purposes).
  * @property {string} [scopedMacroName] - Name of the scoped macro if in scoped content.
  * @property {boolean} isVariableShorthand - Whether this is a variable shorthand (starts with . or $).
  * @property {'.'|'$'|null} variablePrefix - The variable prefix (. for local, $ for global), or null.

         const info = document.createElement('div');
         info.classList.add('macro-ac-scoped-info');
+        // If the scoped content is optional, show a prominent OPTIONAL badge
+        if (this.#context.isScopedContentOptional) {
+            const optionalBadge = document.createElement('span');
+            optionalBadge.classList.add('macro-ac-optional-badge');
+            optionalBadge.textContent = 'OPTIONAL';
+            info.append(optionalBadge);
+        }
         const icon = document.createElement('i');
         icon.classList.add('fa-solid', 'fa-layer-group');
         info.append(icon);
         const text = document.createElement('span');
-        text.innerHTML = `Typing <strong>scoped content</strong> for <code>{{${this.#context.scopedMacroName}}}</code>. Close with <code>{{/${this.#context.scopedMacroName}}}</code>`;
+        const closingHint = this.#context.isScopedContentOptional
+            ? `Can optionally close with <code>{{/${this.#context.scopedMacroName}}}</code>`
+            : `Close with <code>{{/${this.#context.scopedMacroName}}}</code>`;
+        text.innerHTML = `Typing <strong>scoped content</strong> for <code>{{${this.#context.scopedMacroName}}}</code>. ${closingHint}`;
         info.append(text);
         return info;

     /** @type {string} */
     #paddingAfter;
+    /** @type {boolean} */
+    #isOptional;
+    /** @type {number} */
+    #nestingLevel;
     /**
      * @param {string} macroName - The name of the macro to close.
      * @param {Object} [options] - Optional configuration.
      * @param {string} [options.paddingBefore=''] - Whitespace after {{ in opening tag (target padding).
      * @param {string} [options.paddingAfter=''] - Whitespace before }} in opening tag (target padding).
      * @param {string} [options.currentPadding=''] - Whitespace the user has already typed after {{.
+     * @param {boolean} [options.isOptional=false] - Whether this closing tag is for an optional scope.
+     * @param {number} [options.nestingLevel=0] - Nesting level (0 = innermost).
      */
     constructor(macroName, options = {}) {
         // The closing tag is what we're suggesting - use /macroName as the name for matching

         this.#macroName = macroName;
         this.#paddingBefore = options.paddingBefore ?? '';
         this.#paddingAfter = options.paddingAfter ?? '';
+        this.#isOptional = options.isOptional ?? false;
+        this.#nestingLevel = options.nestingLevel ?? 0;
         // Calculate the replacement offset to replace any existing whitespace the user typed
         // This allows us to normalize the whitespace to match the opening tag's style

         // Make selectable so TAB completion works (valueProvider alone makes it non-selectable)
         this.makeSelectable = true;
+        // nameOffset = 2 to skip the {{ prefix in the display for fuzzy highlighting
+        // The name is /macroName but display shows {{/macroName}}
+        this.nameOffset = 2;
         // Highest priority - closing tags should always appear at the very top
         this.sortPriority = 1;
+    }

         help.classList.add('help');
         const content = document.createElement('span');
         content.classList.add('helpContent');
+        // Build description based on optional status and nesting
+        if (this.#isOptional) {
+            const optionalBadge = document.createElement('span');
+            optionalBadge.classList.add('macro-ac-optional-badge', 'macro-ac-optional-badge-small');
+            optionalBadge.textContent = 'OPTIONAL';
+            content.append(optionalBadge);
+            content.append(' ');
+            const nestingInfo = this.#nestingLevel > 0 ? ` (nested ${this.#nestingLevel} level${this.#nestingLevel > 1 ? 's' : ''} deep)` : '';
+            content.append(document.createTextNode(`Optionally close {{${this.#macroName}}}${nestingInfo}`));
+        } else {
             content.textContent = `Close the {{${this.#macroName}}} scoped macro.`;
+        }
         help.append(content);
         li.append(help);

         const details = document.createElement('div');
         details.classList.add('macro-closing-tag-details');
+        // If optional, show badge at the top
+        if (this.#isOptional) {
+            const optionalBadge = document.createElement('span');
+            optionalBadge.classList.add('macro-ac-optional-badge');
+            optionalBadge.textContent = 'OPTIONAL';
+            details.append(optionalBadge);
+        }
         // Header
         const header = document.createElement('h3');
         header.innerHTML = `Close <code>{{${this.#macroName}}}</code>`;

         // Description
         const desc = document.createElement('p');
+        if (this.#isOptional) {
+            const nestingInfo = this.#nestingLevel > 0 ? ` This scope is nested ${this.#nestingLevel} level${this.#nestingLevel > 1 ? 's' : ''} deep.` : '';
+            desc.textContent = `Optionally inserts the closing tag {{/${this.#macroName}}}. The scoped content for this macro is optional - you can close it or leave it open.${nestingInfo}`;
+        } else {
             desc.textContent = `Inserts the closing tag {{/${this.#macroName}}} to complete the scoped macro. The content between the opening and closing tags will be passed as the last argument.`;
+        }
         details.append(desc);
         frag.append(details);

public/scripts/autocomplete/MacroAutoComplete.js+1 -1 Viewed

     const ac = new AutoComplete(
         textarea,
         () => shouldActivateMacroAutocomplete(ac.text, textarea.selectionStart, { isForced: ac.isShowForced, autocompleteMode }),
-        (text, index) => getMacroAutoCompleteAt(text, index),
+        (text, index) => getMacroAutoCompleteAt(text, index, { isForced: ac.isShowForced }),
         true, // isFloating - always use floating mode for free text macro autocomplete
     );

public/scripts/autocomplete/MacroAutoCompleteHelper.js+188 -21 Viewed

  * @property {MacroInfo|null} [macro=null] - Macro info if cursor is inside a macro
  * @property {string|null} [textUpToCursor=null] - Pre-computed text up to cursor
  * @property {UnclosedScope[]|null} [unclosedScopes=null] - Pre-computed unclosed scopes
+ * @property {boolean} [isForced=false] - Whether autocomplete was force-triggered (Ctrl+Space)
  */
 /** @typedef {(EnhancedMacroAutoCompleteOption|MacroFlagAutoCompleteOption|MacroClosingTagAutoCompleteOption|VariableShorthandAutoCompleteOption|VariableNameAutoCompleteOption|VariableOperatorAutoCompleteOption|VariableValueContextAutoCompleteOption|SimpleAutoCompleteOption)} AnyMacroAutoCompleteOption */

         const name = match[3];
         if (isClosing) {
-            // Pop matching opener (case-insensitive)
+            // Find matching opener in stack (case-insensitive)
-            if (stack.length > 0 && stack[stack.length - 1].name.toLowerCase() === name.toLowerCase()) {
+            // When closing an outer scope, all inner unclosed scopes are implicitly closed
-                stack.pop();
+            const matchIndex = stack.findLastIndex(s => s.name.toLowerCase() === name.toLowerCase());
+            if (matchIndex !== -1) {
+                // Pop everything from matchIndex to end (inclusive) - closes the matched scope and all nested ones
+                stack.splice(matchIndex);
+            }
         } else {
             // Check if macro can accept scoped content

+}
 /**
+ * Checks if a scoped macro's scope content is optional (i.e., all required args are already filled).
+ * Used to determine whether to show the scope hint by default or only when forced.
+ *
+ * @param {UnclosedScope} scope - The unclosed scope info.
+ * @param {string} textUpToCursor - The text up to cursor to parse the macro content.
+ * @returns {boolean} - True if the scope content is optional.
+ */
+function isScopeOptional(scope, textUpToCursor) {
+    const def = macroSystem.registry.getPrimaryMacro(scope.name);
+    if (!def) {
+        // Unknown macro - treat scope as required (show hint)
+        return false;
+    }
+    // Find the macro's closing }} to extract its content
+    const openingEnd = textUpToCursor.indexOf('}}', scope.startOffset);
+    if (openingEnd === -1) {
+        // Macro not closed yet - can't determine
+        return false;
+    }
+    // Extract content between {{ and }} to count arguments
+    const macroContent = textUpToCursor.slice(scope.startOffset + 2, openingEnd);
+    const context = parseMacroContext(macroContent, macroContent.length);
+    // Count current arguments (including space-separated arg if present)
+    const currentArgCount = context.args.length;
+    // The scoped content would be the next argument (currentArgCount + 1)
+    // Scope is optional if:
+    // 1. Current args already meet minArgs requirement, AND
+    // 2. Adding one more (scope) would still be <= maxArgs
+    const wouldBeArgIndex = currentArgCount; // 0-indexed
+    const scopeIsOptional = currentArgCount >= def.minArgs && wouldBeArgIndex < def.maxArgs;
+    // Check if the argument at wouldBeArgIndex is marked as optional in the definition
+    if (def.unnamedArgDefs && def.unnamedArgDefs[wouldBeArgIndex]) {
+        return def.unnamedArgDefs[wouldBeArgIndex].optional === true;
+    }
+    // If no explicit arg definition, use the min/max args logic
+    return scopeIsOptional;
+}
+/**
+ * Filters unclosed scopes to exclude those with optional scope content.
+ * Used when autocomplete is not force-triggered (Ctrl+Space).
+ *
+ * @param {UnclosedScope[]} unclosedScopes - The unclosed scopes to filter.
+ * @param {string} textUpToCursor - The text up to cursor.
+ * @param {boolean} isForced - Whether autocomplete was force-triggered.
+ * @returns {UnclosedScope[]} - Filtered scopes (excludes optional scopes unless forced).
+ */
+function filterOptionalScopes(unclosedScopes, textUpToCursor, isForced) {
+    if (isForced) {
+        // When forced, show all scopes including optional ones
+        return unclosedScopes;
+    }
+    // Filter out scopes where the scope content is optional
+    return unclosedScopes.filter(scope => !isScopeOptional(scope, textUpToCursor));
+}
+/**
  * Builds autocomplete options for variable shorthand syntax (.varName or $varName).
  * @param {MacroAutoCompleteContext} context
  * @param {Object} [opts] - Optional configuration.

  * When typing arguments (after ::), prioritizes the exact macro match.
  * @param {MacroAutoCompleteContext} context
  * @param {string} [textUpToCursor] - Full document text up to cursor, for unclosed scope detection.
+ * @param {Object} [opts] - Additional options.
+ * @param {boolean} [opts.isForced=false] - Whether autocomplete was force-triggered (Ctrl+Space).
  * @returns {AnyMacroAutoCompleteOption[]}
  */
-export function buildEnhancedMacroOptions(context, textUpToCursor) {
+export function buildEnhancedMacroOptions(context, textUpToCursor, { isForced = false } = {}) {
     /** @type {AnyMacroAutoCompleteOption[]} */
     const options = [];

         return buildVariableShorthandOptions(context);
+    }
-    // Check for unclosed scoped macros and suggest closing tags first
+    // Check for unclosed scoped macros and suggest closing tags
+    // Iterate from innermost to outermost, adding optional scopes and stopping at first required scope
     const unclosedScopes = findUnclosedScopes(textUpToCursor);
     if (unclosedScopes.length > 0) {
-        // Suggest closing the innermost (last) unclosed scope first
+        let firstRequiredPriority = 1; // Priority for the first required (non-optional) scope
-        const innermostScope = unclosedScopes[unclosedScopes.length - 1];
+        let optionalPriority = 3; // Lower priority for optional scopes
-        // Preserve whitespace padding from the opening tag
+        let foundRequired = false;
-        // Pass currentPadding so the closing tag can replace user-typed whitespace with the target padding
+        let elseOptionAdded = false;
-        const closingOption = new MacroClosingTagAutoCompleteOption(innermostScope.name, {
-            paddingBefore: innermostScope.paddingBefore,
+        // Iterate from innermost (last) to outermost (first)
-            paddingAfter: innermostScope.paddingAfter,
+        for (let i = unclosedScopes.length - 1; i >= 0; i--) {
+            const scope = unclosedScopes[i];
+            const isOptional = isScopeOptional(scope, textUpToCursor);
+            const nestingLevel = unclosedScopes.length - 1 - i; // 0 = innermost
+            // If we've already found a required scope, stop adding more
+            if (foundRequired && !isOptional) break;
+            const closingOption = new MacroClosingTagAutoCompleteOption(scope.name, {
+                paddingBefore: scope.paddingBefore,
+                paddingAfter: scope.paddingAfter,
                 currentPadding: context.paddingBefore,
+                isOptional: isOptional,
+                nestingLevel: nestingLevel,
             });
+            if (isOptional) {
+                closingOption.sortPriority = optionalPriority++;
+            } else {
+                // First required scope gets top priority
+                closingOption.sortPriority = firstRequiredPriority;
+                foundRequired = true;
+            }
             options.push(closingOption);
-        // If inside a scoped {{if}}, also suggest {{else}}
+            // If inside a scoped {{if}}, also suggest {{else}} (only once, for innermost if)
-        if (innermostScope.name === 'if') {
+            if (!elseOptionAdded && scope.name === 'if') {
                 const macroDef = macroSystem.registry.getPrimaryMacro('else');
                 const elseOption = new EnhancedMacroAutoCompleteOption(macroDef);
                 elseOption.sortPriority = 2;
                 options.push(elseOption);
+                elseOptionAdded = true;
+            }
+            // Stop once we've added a required scope
+            if (foundRequired) break;
+        }
+    }

+        }
+    }
-    // If typing args/closing brace but no macro matches, add a "no match" indicator
+    // If typing args/closing brace but no macro matches, check for closing macro context
     if (shouldShowMatchingMacroDetails && !hasMatchingMacro && context.identifier.length > 0) {
+        // Check if this is a closing macro (starts with /) - show original macro's details
+        // Note: We look up the macro directly, not from unclosedScopes, because the closing tag
+        // itself may have already closed the scope by this point in the text
+        const isClosingMacro = context.identifier.startsWith('/');
+        const closingMacroName = isClosingMacro ? context.identifier.slice(1) : null;
+        const macroDef = closingMacroName ? macroSystem.registry.getPrimaryMacro(closingMacroName) : null;
+        if (macroDef) {
+            // Show the original macro's details for the closing tag
+            // Create a context that shows we're closing the scope (no argument highlight)
+            const closingContext = /** @type {MacroAutoCompleteContext} */ ({
+                ...context,
+                identifier: macroDef.name,
+                currentArgIndex: -1, // No argument highlight
+                isClosingTag: true,
+            });
+            const closingOption = new EnhancedMacroAutoCompleteOption(macroDef, closingContext);
+            closingOption.valueProvider = () => '';
+            closingOption.makeSelectable = false;
+            closingOption.matchProvider = () => true;
+            closingOption.sortPriority = 0;
+            options.unshift(closingOption);
+            hasMatchingMacro = true; // Prevent "no match" message
+        }
+        // Only show "no match" if we didn't find a matching closing scope
+        if (!hasMatchingMacro) {
             const noMatchOption = new SimpleAutoCompleteOption({
                 name: context.identifier,
                 symbol: '❌',

@@ -539,6 +663,7 @@ export function buildEnhancedMacroOptions(context, textUpToCursor) {
539	noMatchOption.sortPriority = 0; // Top priority	663	noMatchOption.sortPriority = 0; // Top priority
540	options.unshift(noMatchOption);	664	options.unshift(noMatchOption);
541	}	665	}
		666	}
542		667
543	return options;	668	return options;
544	}	669	}

     macro = null,
     textUpToCursor = null,
     unclosedScopes = null,
+    isForced = false,
 } = {}) {
     // Compute textUpToCursor if not provided
     if (textUpToCursor === null) {

         unclosedScopes = findUnclosedScopes(textUpToCursor);
+    }
+    // Filter out optional scopes unless forced (Ctrl+Space)
+    // This prevents intrusive hints for macros like {{trim}} where scope is optional
+    const filteredScopes = filterOptionalScopes(unclosedScopes, textUpToCursor, isForced);
     // If cursor is NOT inside a macro, check if we're in scoped content
     if (!macro) {
-        if (unclosedScopes.length > 0) {
+        if (filteredScopes.length > 0) {
-            const scopedMacro = unclosedScopes[unclosedScopes.length - 1];
+            const scopedMacro = filteredScopes[filteredScopes.length - 1];
             // Find where the opening macro ends
             const openingEnd = text.indexOf('}}', scopedMacro.startOffset);

                 const macroContent = text.slice(scopedMacro.startOffset + 2, openingEnd);
                 const baseContext = parseMacroContext(macroContent, macroContent.length);
+                // Check if this scope is optional (for display purposes)
+                const scopeIsOptional = isScopeOptional(scopedMacro, textUpToCursor);
                 const scopedContext = {
                     ...baseContext,
                     currentArgIndex: baseContext.args.length,
                     isInScopedContent: true,
+                    isScopedContentOptional: scopeIsOptional,
                     scopedMacroName: scopedMacro.name,
                 };

     if (isCursorAtClosing) {
         // Cursor is at the closing }} - check if this is an unclosed scoped macro
-        if (unclosedScopes.length > 0) {
+        if (filteredScopes.length > 0) {
-            const scopedMacro = unclosedScopes[unclosedScopes.length - 1];
+            const scopedMacro = filteredScopes[filteredScopes.length - 1];
             // Check if the current macro IS the unclosed scoped macro
             if (scopedMacro.startOffset === macro.start) {
                 // Show scoped context - cursor is right at the end of the opening tag
+                // Check if this scope is optional (for display purposes)
+                const scopeIsOptional = isScopeOptional(scopedMacro, textUpToCursor);
                 const scopedContext = {
                     ...context,
                     currentArgIndex: context.args.length,
                     isInScopedContent: true,
+                    isScopedContentOptional: scopeIsOptional,
                     scopedMacroName: scopedMacro.name,
                 };

+                }
+            }
+        }
+        // Check if this is a closing tag ({{/macroName}}) - show original macro's details
+        // Note: We look up the macro directly, not from unclosedScopes, because the closing tag
+        // itself has already closed the scope by this point in the text
+        if (context.identifier.startsWith('/')) {
+            const closingMacroName = context.identifier.slice(1);
+            const macroDef = macroSystem.registry.getPrimaryMacro(closingMacroName);
+            if (macroDef) {
+                const closingContext = /** @type {MacroAutoCompleteContext} */ ({
+                    ...context,
+                    identifier: macroDef.name,
+                    currentArgIndex: -1, // No argument highlight
+                    isClosingTag: true,
+                });
+                const closingOption = new EnhancedMacroAutoCompleteOption(macroDef, closingContext);
+                closingOption.valueProvider = () => '';
+                closingOption.makeSelectable = false;
+                return new AutoCompleteNameResult(
+                    macroDef.name,
+                    macro.start + 2,
+                    [closingOption],
+                    false,
+                );
+            }
+        }
         // Not a scoped macro, just clear arg highlighting
         context.currentArgIndex = -1;
+    }

+ *
  * @param {string} text - The full text content.
  * @param {number} cursorPos - The cursor position.
+ * @param {Object} [options={}] - Additional options.
+ * @param {boolean} [options.isForced=false] - Whether autocomplete was force-triggered (Ctrl+Space).
  * @returns {Promise<AutoCompleteNameResult|null>}
  */
-export async function getMacroAutoCompleteAt(text, cursorPos) {
+export async function getMacroAutoCompleteAt(text, cursorPos, { isForced = false } = {}) {
     const macro = findMacroAtCursor(text, cursorPos);
-    return buildMacroAutoCompleteResult(text, cursorPos, { macro });
+    return buildMacroAutoCompleteResult(text, cursorPos, { macro, isForced });
+}

public/scripts/macros/engine/MacroCstWalker.js+6 -3 Viewed

             if (!info) continue;
             if (info.isClosing) {
-                // Closing tag - pop matching opener from stack (case-insensitive match)
+                // Find matching opener in stack (case-insensitive)
-                if (unclosedStack.length > 0 && unclosedStack[unclosedStack.length - 1].name.toLowerCase() === info.name.toLowerCase()) {
+                // When closing an outer scope, all inner unclosed scopes are implicitly closed
-                    unclosedStack.pop();
+                const matchIndex = unclosedStack.findLastIndex(s => s.name.toLowerCase() === info.name.toLowerCase());
+                if (matchIndex !== -1) {
+                    // Pop everything from matchIndex to end (inclusive) - closes the matched scope and all nested ones
+                    unclosedStack.splice(matchIndex);
+                }
                 // If no matching opener, ignore (orphan closing tag)
             } else {