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+56 -3 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');
 -        content.textContent = `Close the {{${this.#macroName}}} scoped macro.`;
++
 +        // 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');
 -        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.`;
 +        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, { isForced: ac.isShowForced }),
         true, // isFloating - always use floating mode for free text macro autocomplete
     );

public/scripts/autocomplete/MacroAutoCompleteHelper.js+208 -41 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) {
             // PopFind 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, { isForced = false } = {}) {
     /** @type {AnyMacroAutoCompleteOption[]} */
     const options = [];

         return buildVariableShorthandOptions(context);
+    }
     // Check for unclosed scoped macros and suggest closing tags first
 +    // Iterate from innermost to outermost, adding optional scopes and stopping at first required scope
     const unclosedScopes = findUnclosedScopes(textUpToCursor);
     if (unclosedScopes.length > 0) {
         let firstRequiredPriority = 1; // SuggestPriority closingfor the innermostfirst required (lastnon-optional) unclosed scope first
 -        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--) {
 -            currentPadding: context.paddingBefore,
 +            const scope = unclosedScopes[i];
 -        });
 +            const isOptional = isScopeOptional(scope, textUpToCursor);
 -        options.push(closingOption);
 +            const nestingLevel = unclosedScopes.length - 1 - i; // 0 = innermost
 -        // If inside a scoped {{if}}, also suggest {{else}}
 +            // If we've already found a required scope, stop adding more
 -        if (innermostScope.name === 'if') {
 +            if (foundRequired && !isOptional) break;
 -            const macroDef = macroSystem.registry.getPrimaryMacro('else');
++
             const elseOptionclosingOption = new EnhancedMacroAutoCompleteOptionMacroClosingTagAutoCompleteOption(macroDef);scope.name, {
 -            elseOption.sortPriority = 2;
 +                paddingBefore: scope.paddingBefore,
 -            options.push(elseOption);
 +                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}} (only once, for innermost 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, addcheck afor "noclosing match"macro indicatorcontext
     if (shouldShowMatchingMacroDetails && !hasMatchingMacro && context.identifier.length > 0) {
 -        const noMatchOption = new SimpleAutoCompleteOption({
 +        // Check if this is a closing macro (starts with /) - show original macro's details
 -            name: context.identifier,
 +        // Note: We look up the macro directly, not from unclosedScopes, because the closing tag
 -            symbol: '❌',
 +        // itself may have already closed the scope by this point in the text
 -            description: `No macro found: "${context.identifier}"`,
 +        const isClosingMacro = context.identifier.startsWith('/');
 -            detailedDescription: `The macro name <code>${context.identifier}</code> does not exist.<br><br>Check spelling or use a different macro name.`,
 +        const closingMacroName = isClosingMacro ? context.identifier.slice(1) : null;
 -            type: 'error',
 +        const macroDef = closingMacroName ? macroSystem.registry.getPrimaryMacro(closingMacroName) : null;
 -        });
++
 -        noMatchOption.valueProvider = () => '';
 +        if (macroDef) {
 -        noMatchOption.makeSelectable = false;
 +            // Show the original macro's details for the closing tag
 -        noMatchOption.matchProvider = () => true; // Always show
 +            // Create a context that shows we're closing the scope (no argument highlight)
 -        noMatchOption.sortPriority = 0; // Top priority
 +            const closingContext = /** @type {MacroAutoCompleteContext} */ ({
 -        options.unshift(noMatchOption);
 +                ...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: '❌',
 +                description: `No macro found: "${context.identifier}"`,
 +                detailedDescription: `The macro name <code>${context.identifier}</code> does not exist.<br><br>Check spelling or use a different macro name.`,
 +                type: 'error',
 +            });
 +            noMatchOption.valueProvider = () => '';
 +            noMatchOption.makeSelectable = false;
 +            noMatchOption.matchProvider = () => true; // Always show
 +            noMatchOption.sortPriority = 0; // Top priority
 +            options.unshift(noMatchOption);
 +        }
+    }
     return options;

     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 (unclosedScopesfilteredScopes.length > 0) {
             const scopedMacro = unclosedScopesfilteredScopes[unclosedScopesfilteredScopes.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 (unclosedScopesfilteredScopes.length > 0) {
             const scopedMacro = unclosedScopesfilteredScopes[unclosedScopesfilteredScopes.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, { isForced = false } = {}) {
     const macro = findMacroAtCursor(text, cursorPos);
     return buildMacroAutoCompleteResult(text, cursorPos, { macro, isForced });
+}

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

             if (!info) continue;
             if (info.isClosing) {
                 // Closing tag - popFind matching opener fromin stack (case-insensitive match)
 -                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 {