feat(editor): show outline boxes around active snippet tab-stops

TabstopManager now draws a subdued box around every remaining tab-stop
in an active session, with a bolder box layered on top of whichever
stop is currently selected - matching the visual language
RenameIdentifier.js already uses for its rename boxes. Benefits every
consumer of the shared tab-stop engine (LSP completions, DocComment
hints, Custom Snippets), not just one feature.

Uses a new @bc-editor-decoration-neutral variable (no light/dark
split) for the subdued box, since it decorates the code editor canvas
whose background depends on the user's code theme, not the app's
light/dark UI mode - same reasoning as .cm-matchhighlight. The active
box reuses the existing @bc-primary-btn-border/@dark-bc-primary-btn-border
pair split by .dark& for consistency with rename's own accent color.

Adds unit coverage for marker class assignment, active-marker swap on
navigation, zero-width stops correctly getting no box, and both
markers clearing on session end.

Author: abose

src/editor/Editor.js

@@ -1396,6 +1396,37 @@ define(function (require, exports, module) {
         };
     }
 
+    /**
+     * Mark option for a subdued outline box, used to show every remaining stop of an active
+     * snippet/tab-stop session (see editor/TabstopManager.js) so the user can see at a glance how
+     * many fields are left and where, even for the ones they haven't tabbed to yet.
+     */
+    function getMarkOptionTabstopOutline() {
+        return {
+            className: "editor-text-tabstop-outline",
+            startStyle: "editor-text-tabstop-outline-left",
+            endStyle: "editor-text-tabstop-outline-right",
+            clearWhenEmpty: false,
+            inclusiveLeft: true,
+            inclusiveRight: true
+        };
+    }
+
+    /**
+     * Mark option for the bold/active variant of the above, layered on top of it for whichever stop
+     * is currently selected in an active snippet/tab-stop session.
+     */
+    function getMarkOptionTabstopOutlineActive() {
+        return {
+            className: "editor-text-tabstop-outline-active",
+            startStyle: "editor-text-tabstop-outline-active-left",
+            endStyle: "editor-text-tabstop-outline-active-right",
+            clearWhenEmpty: false,
+            inclusiveLeft: true,
+            inclusiveRight: true
+        };
+    }
+
     /**
      * Mark option to underline errors.
      */
@@ -1430,6 +1461,8 @@ define(function (require, exports, module) {
      * Mark option for renaming outlines.
      */
     Editor.getMarkOptionRenameOutline = getMarkOptionRenameOutline;
+    Editor.getMarkOptionTabstopOutline = getMarkOptionTabstopOutline;
+    Editor.getMarkOptionTabstopOutlineActive = getMarkOptionTabstopOutlineActive;
 
     /**
      * Can be used to mark a range of text with a specific CSS class name. cursorFrom and cursorTo should be {line, ch}

src/editor/TabstopManager.js

@@ -35,11 +35,19 @@
  *     stop, and (when there is more than one stop) starts a Tab-navigable session backed by markers
  *     so the stops follow any later edits (e.g. an auto-import line inserted above).
  *
- * NOTE: this is currently wired only into the LSP completion path (languageTools/DefaultProviders).
- * The Emmet expander (HTMLCodeHints) and the custom-snippets feature have their own stable cursor
- * handling and were intentionally left untouched; they can migrate onto this manager in future.
+ * Used by the LSP completion path (languageTools/DefaultProviders), DocCommentHints, and Custom
+ * Snippets (extensionsIntegrated/CustomSnippets/snippetCursorManager.js). The Emmet expander
+ * (HTMLCodeHints) still has its own separate cursor handling.
+ *
+ * While a Tab-navigable session is active, every remaining stop gets a subdued outline box (see
+ * Editor.getMarkOptionTabstopOutline) so the user can see at a glance how many fields are left and
+ * where, with the currently-selected one getting a bolder "active" outline layered on top (see
+ * Editor.getMarkOptionTabstopOutlineActive) - matches the visual language RenameIdentifier.js already
+ * uses for its own outline box. Zero-width stops (a bare `$N`/`$0` with no default text - just a
+ * caret position, no marker range) don't get an outline, since there's no span to box.
  */
 define(function (require, exports, module) {
+    const Editor = require("editor/Editor").Editor;
 
     /**
      * Expand an LSP snippet into plain text plus the list of tab-stops.
@@ -174,7 +182,7 @@ define(function (require, exports, module) {
 
     // ---- Tab-navigation session ----------------------------------------------------------------
 
-    var _session = null;   // { editor, markers: [marker], index, keymap }
+    var _session = null;   // { editor, markers: [marker], index, keymap, activeOutlineMarker }
 
     function _clearSession() {
         if (!_session) {
@@ -185,6 +193,9 @@ define(function (require, exports, module) {
         session.markers.forEach(function (m) {
             m.clear();
         });
+        if (session.activeOutlineMarker) {
+            session.activeOutlineMarker.clear();
+        }
         session.editor._codeMirror.removeKeyMap(session.keymap);
         session.editor.off(".tabstop");
     }
@@ -251,6 +262,17 @@ define(function (require, exports, module) {
         }
         _session.index = index;
         _session.editor.setSelection(range.from, range.to);
+
+        // swap the bold "active" outline onto whichever stop we just landed on - only meaningful for
+        // a real span (a bare $N/$0 with no default text is a zero-width caret, nothing to box)
+        if (_session.activeOutlineMarker) {
+            _session.activeOutlineMarker.clear();
+            _session.activeOutlineMarker = null;
+        }
+        if (range.from.line !== range.to.line || range.from.ch !== range.to.ch) {
+            _session.activeOutlineMarker = _session.editor.markText(
+                "tabstop-active", range.from, range.to, Editor.getMarkOptionTabstopOutlineActive());
+        }
         return true;
     }
 
@@ -332,6 +354,11 @@ define(function (require, exports, module) {
         }
 
         // Multiple stops: lay down markers and start a Tab-navigable session.
+        // the subdued outline (visual only) is layered onto the SAME functional tracking options
+        // below by className/startStyle/endStyle alone - deliberately not spreading the whole helper
+        // object in, since its own inclusiveLeft/clearWhenEmpty differ from what marker TRACKING here
+        // actually needs (inclusiveLeft: false is what makes typing at a stop's start not stick to it).
+        var outlineOption = Editor.getMarkOptionTabstopOutline();
         var markers = parsed.stops.map(function (stop) {
             var ms = posFromOffset(stop.start),
                 me = posFromOffset(stop.end);
@@ -341,7 +368,10 @@ define(function (require, exports, module) {
             return editor.markText("tabstop", ms, me, {
                 clearWhenEmpty: false,
                 inclusiveLeft: false,
-                inclusiveRight: true
+                inclusiveRight: true,
+                className: outlineOption.className,
+                startStyle: outlineOption.startStyle,
+                endStyle: outlineOption.endStyle
             });
         });
 
@@ -358,7 +388,7 @@ define(function (require, exports, module) {
             }
         };
 
-        _session = { editor: editor, markers: markers, index: -1, keymap: keymap };
+        _session = { editor: editor, markers: markers, index: -1, keymap: keymap, activeOutlineMarker: null };
         editor._codeMirror.addKeyMap(keymap);
         // End the session if the editor it belongs to is destroyed (file closed), or the user moves
         // on (cursor leaves the snippet's lines, or a multi-cursor selection is made). Namespaced so

src/styles/brackets.less

@@ -190,6 +190,58 @@ html, body {
     box-shadow: inset 1px 0 0 0 @bc-primary-btn-border, inset -1px 0 0 0 @bc-primary-btn-border; /* Left, right shadow */
 }
 
+// Subdued outline shown for every remaining stop of an active snippet/tab-stop session (see
+// editor/TabstopManager.js) - a neutral border color, distinct from the bold "active" variant below.
+// Uses @bc-editor-decoration-neutral (no .dark & split - see its own definition for why editor-canvas
+// decorations need one universal mid-tone value instead of a light/dark UI-chrome color pair).
+.editor-text-tabstop-outline {
+    border-top: 1px @bc-editor-decoration-neutral solid;
+    border-bottom: 1px @bc-editor-decoration-neutral solid;
+}
+.editor-text-tabstop-outline-left {
+    box-shadow: inset 1px 0 0 0 @bc-editor-decoration-neutral; /* Left shadow */
+}
+.editor-text-tabstop-outline-right {
+    box-shadow: inset -1px 0 0 0 @bc-editor-decoration-neutral; /* right shadow */
+}
+.editor-text-tabstop-outline-left.editor-text-tabstop-outline-right {
+    box-shadow: inset 1px 0 0 0 @bc-editor-decoration-neutral, inset -1px 0 0 0 @bc-editor-decoration-neutral; /* Left, right shadow */
+}
+
+// Bold/active outline for whichever stop is currently selected, layered on top of the subdued one
+// above (same accent color rename-outline uses, for a consistent "you're actively editing here"
+// visual language across features).
+.editor-text-tabstop-outline-active {
+    border-top: 1px @bc-primary-btn-border solid;
+    border-bottom: 1px @bc-primary-btn-border solid;
+
+    .dark & {
+        border-top: 1px @dark-bc-primary-btn-border solid;
+        border-bottom: 1px @dark-bc-primary-btn-border solid;
+    }
+}
+.editor-text-tabstop-outline-active-left {
+    box-shadow: inset 1px 0 0 0 @bc-primary-btn-border;
+
+    .dark & {
+        box-shadow: inset 1px 0 0 0 @dark-bc-primary-btn-border;
+    }
+}
+.editor-text-tabstop-outline-active-right {
+    box-shadow: inset -1px 0 0 0 @bc-primary-btn-border;
+
+    .dark & {
+        box-shadow: inset -1px 0 0 0 @dark-bc-primary-btn-border;
+    }
+}
+.editor-text-tabstop-outline-active-left.editor-text-tabstop-outline-active-right {
+    box-shadow: inset 1px 0 0 0 @bc-primary-btn-border, inset -1px 0 0 0 @bc-primary-btn-border;
+
+    .dark & {
+        box-shadow: inset 1px 0 0 0 @dark-bc-primary-btn-border, inset -1px 0 0 0 @dark-bc-primary-btn-border;
+    }
+}
+
 // error class has highest visual precedence, followed by warning, spell error and info.
 // .error.error: This selector has 4x the class name, which increases its specificity compared to single class
 // selectors like .warning or .info. Even if error, warning, and info are used on the same div in any order,

src/styles/brackets_core_ui_variables.less

@@ -65,6 +65,12 @@
 @bc-error:                      #f74687;
 @bc-modal-backdrop-opacity:     0.4;
 @bc-spinner:                    #78b2f2;
+// Deliberately NOT theme-split (no @dark- pair): this decorates the EDITOR CANVAS, whose background
+// depends on the user's chosen code theme (not just the app's light/dark UI mode - see
+// .cm-matchhighlight in brackets_codemirror_override.less for the same reasoning), so it needs one
+// mid-tone value that reads reasonably against both very light and very dark editor backgrounds,
+// rather than a UI-chrome color pair tuned only for the app's own near-white/near-black panels.
+@bc-editor-decoration-neutral:  #808080;
 
 // Highlights and Shadows
 @bc-highlight:                  rgba(255, 255, 255, 0.12);

test/spec/TabstopManager-test.js

@@ -387,6 +387,60 @@ define(function (require, exports, module) {
                     expect(myEditor.getSelectedText()).toBe("a"); // two backward moves: c -> b -> a
                 });
             });
+
+            // Visual boxing while a session is active - see Editor.getMarkOptionTabstopOutline/
+            // getMarkOptionTabstopOutlineActive and brackets.less .editor-text-tabstop-outline*.
+            describe("visual outline markers", function () {
+                function outlineMarks(className) {
+                    return myEditor._codeMirror.getAllMarks().filter(function (m) {
+                        return m.className === className;
+                    });
+                }
+
+                it("should give every range-based stop a subdued outline marker on insertion", function () {
+                    createTestEditor("");
+                    TabstopManager.insertSnippet(myEditor, "${1:a} ${2:b} $0", ORIGIN, ORIGIN);
+                    // 2 range stops (a, b) get the subdued outline; $0 (zero-width, no default) does not
+                    expect(outlineMarks("editor-text-tabstop-outline").length).toBe(2);
+                });
+
+                it("should give only the CURRENTLY selected stop the bold active outline", function () {
+                    createTestEditor("");
+                    TabstopManager.insertSnippet(myEditor, "${1:a} ${2:b} $0", ORIGIN, ORIGIN);
+                    expect(outlineMarks("editor-text-tabstop-outline-active").length).toBe(1);
+
+                    pressTab();
+                    expect(outlineMarks("editor-text-tabstop-outline-active").length).toBe(1);
+                });
+
+                it("should move the active outline as the user tabs, keeping the subdued ones in place",
+                    function () {
+                        createTestEditor("");
+                        TabstopManager.insertSnippet(myEditor, "${1:a} ${2:b} $0", ORIGIN, ORIGIN);
+                        expect(outlineMarks("editor-text-tabstop-outline-active")[0].find().from.ch).toBe(0); // "a"
+
+                        pressTab();
+                        expect(outlineMarks("editor-text-tabstop-outline-active")[0].find().from.ch).toBe(2); // "b"
+                        // both subdued outlines (a and b) are still there, untouched
+                        expect(outlineMarks("editor-text-tabstop-outline").length).toBe(2);
+                    });
+
+                it("should not give a zero-width stop (no default text) any active outline", function () {
+                    createTestEditor("");
+                    TabstopManager.insertSnippet(myEditor, "${1:a} $2 $0", ORIGIN, ORIGIN);
+                    pressTab(); // -> $2, a bare zero-width stop
+                    expect(myEditor.getSelectedText()).toBe("");
+                    expect(outlineMarks("editor-text-tabstop-outline-active").length).toBe(0);
+                });
+
+                it("should clear all outline markers when the session ends", function () {
+                    createTestEditor("");
+                    TabstopManager.insertSnippet(myEditor, "${1:a} ${2:b} $0", ORIGIN, ORIGIN);
+                    TabstopManager.endSession();
+                    expect(outlineMarks("editor-text-tabstop-outline").length).toBe(0);
+                    expect(outlineMarks("editor-text-tabstop-outline-active").length).toBe(0);
+                });
+            });
         });
     });
 });