feature(gutter): add ability to replace fold icon with custom for a specific row

nlujjawal · nlujjawal · commit 0dc96b2f3f5c · 2025-04-03T10:39:58.000+02:00
diff --git a/src/css/editor-css.js b/src/css/editor-css.js
@@ -507,7 +507,7 @@ module.exports = `
     padding-right: 13px;
 }
 
-.ace_fold-widget {
+.ace_fold-widget, .ace_custom-widget {
     box-sizing: border-box;
 
     margin: 0 -12px 0 1px;
diff --git a/src/edit_session.js b/src/edit_session.js
@@ -585,6 +585,27 @@ class EditSession {
         this._signal("changeBreakpoint", {});
     }
 
+    /**
+     * Replaces the custom icon with the fold widget if present from a specific row in the gutter
+     * @param {number} row The row number for which to hide the custom icon
+     */
+    hideGutterCustomWidget(row) {
+        this.$editor.renderer.$gutterLayer.hideCustomWidget(row);
+    }
+
+    /**
+     * Replaces the fold widget if present with the custom icon from a specific row in the gutter
+     * @param {number} row - The row number where the widget will be displayed
+     * @param {Object} options - Configuration options for the widget
+     * @param {string} options.className - CSS class name for styling the widget
+     * @param {string} options.label - Text label to display in the widget
+     *  @param {string} options.title - Tooltip text for the widget
+     * @returns {void}
+    */
+    showGutterCustomWidget(row,attributes) {
+        this.$editor.renderer.$gutterLayer.showCustomWidget(row,attributes);
+    }
+
     /**
      * Removes `className` from the `row`.
      * @param {Number} row The row number
diff --git a/src/layer/gutter.js b/src/layer/gutter.js
@@ -331,6 +331,7 @@ class Gutter{
         
         var textNode = element.childNodes[0];
         var foldWidget = element.childNodes[1];
+        var customWidget = element.childNodes[3];
         var annotationNode = element.childNodes[2];
         var annotationIconNode = annotationNode.firstChild;
 
@@ -418,6 +419,10 @@ class Gutter{
             // Set a11y properties.
             foldWidget.setAttribute("role", "button");
             foldWidget.setAttribute("tabindex", "-1");
+
+            if(customWidget && window.getComputedStyle(customWidget).getPropertyValue('display') !== 'none'){
+                this.hideFoldWidget(row);
+            }
             var foldRange = session.getFoldWidgetRange(row);
 
             // getFoldWidgetRange is optional to be implemented by fold modes, if not available we fall-back.
@@ -588,6 +593,89 @@ class Gutter{
     getShowFoldWidgets() {
         return this.$showFoldWidgets;
     }
+    
+    /**
+     * Hides the fold widget/icon from a specific row in the gutter
+     * @param {number} row The row number from which to hide the fold icon
+     */
+    hideFoldWidget(row) {
+        const cells = this.$lines.cells;
+        const cell = cells[row];
+        if (cell && cell.element) {
+            const foldWidget = cell.element.childNodes[1];
+            if (foldWidget) {
+                dom.setStyle(foldWidget.style, "display", "none");
+            }
+        }
+    }
+
+    /**
+     * Shows the fold widget/icon from a specific row in the gutter
+     * @param {number} row The row number from which to show the fold icon
+     */
+    showFoldWidget(row) {
+        const cells = this.$lines.cells;
+        const cell = cells[row];
+        if (cell && cell.element) {
+            const foldWidget = cell.element.childNodes[1];
+            if (foldWidget) {
+                dom.setStyle(foldWidget.style, "display", "inline-block");
+            }
+        }
+    }
+
+    /**
+    * Displays a custom widget for a specific row
+    * @param {number} row - The row number where the widget will be displayed
+    * @param {Object} options - Configuration options for the widget
+    * @param {string} options.className - CSS class name for styling the widget
+    * @param {string} options.label - Text label to display in the widget
+    * @param {string} options.title - Tooltip text for the widget
+    * @returns {void}
+    */
+    showCustomWidget(row, {className, label, title}) {
+        const cells = this.$lines.cells;
+        const cell = cells[row];
+        if (cell && cell.element) {
+            var customWidget = cell.element.querySelector(".ace_custom-widget");
+                this.hideFoldWidget(row);
+                // if customWidget already exists show it.
+            if (customWidget) {
+                dom.setStyle(customWidget.style, "display", "inline-block");
+            }
+            else {
+                // if customWidget doesn't exists create it.
+                customWidget = dom.createElement("span");
+
+                customWidget.className = `ace_custom-widget ${className}`;
+                customWidget.setAttribute("tabindex", "-1");
+                customWidget.setAttribute("role", 'button');
+                customWidget.setAttribute("aria-label", label);
+                customWidget.setAttribute("title", title);
+                dom.setStyle(customWidget.style, "display", "inline-block");
+                dom.setStyle(customWidget.style, "height", "inherit");
+                
+                cell.element.appendChild(customWidget);
+            }
+        }
+    }
+    
+    /**
+    * Hides a custom widget for a specific row
+    * @param {number} row - The row number where the widget will be hidden
+    * @returns {void}
+    */
+    hideCustomWidget(row){
+        const cells = this.$lines.cells;
+        const cell = cells[row];
+        if (cell && cell.element) {
+            const customWidget = cell.element.querySelector(".ace_custom-widget");
+            if (customWidget) {
+                dom.setStyle(customWidget.style, "display", "none");
+            }
+        this.showFoldWidget(row);
+        }
+    }
 
     $computePadding() {
         if (!this.element.firstChild)
diff --git a/src/layer/gutter_test.js b/src/layer/gutter_test.js
@@ -0,0 +1,130 @@
+if (typeof process !== "undefined") {
+    require("amd-loader");
+    require("../test/mockdom");
+}
+
+var keys = require('../lib/keys');
+
+"use strict";
+
+require("../multi_select");
+require("../theme/textmate");
+var Editor = require("../editor").Editor;
+var Mode = require("../mode/java").Mode;
+var VirtualRenderer = require("../virtual_renderer").VirtualRenderer;
+var assert = require("../test/assertions");
+
+function emit(keyCode) {
+    var data = {bubbles: true, keyCode};
+    var event = new KeyboardEvent("keydown", data);
+
+    var el = document.activeElement;
+    el.dispatchEvent(event);
+}
+
+module.exports = {
+    setUp : function(done) {
+        this.editor = new Editor(new VirtualRenderer());
+        this.editor.container.style.position = "absolute";
+        this.editor.container.style.height = "500px";
+        this.editor.container.style.width = "500px";
+        this.editor.container.style.left = "50px";
+        this.editor.container.style.top = "10px";
+        document.body.appendChild(this.editor.container);
+        done();
+    },
+    "test: custom icon replaces the fold icon sucessfully" : function(done) {
+            var editor = this.editor;
+            var value = "x {" + "\n".repeat(50) + "}\n";
+            value = value.repeat(50);
+            editor.session.setMode(new Mode());
+            editor.setValue(value, -1);
+            editor.setOption("enableKeyboardAccessibility", true);
+            editor.renderer.$loop._flush();
+    
+            var lines = editor.renderer.$gutterLayer.$lines;
+    
+            // Set focus to the gutter div.
+            editor.renderer.$gutter.focus();
+            assert.equal(document.activeElement, editor.renderer.$gutter);
+    
+            // Focus on the fold widget.
+            emit(keys["enter"]);
+            editor.renderer.$gutterLayer.showCustomWidget(13, {
+                className: "ace_users_css",
+                label: "Open_label",
+                title: "Open_title"
+            });
+    
+            setTimeout(function() {
+                setTimeout(function() {
+                    // Check that custom widget is shown
+                    editor.renderer.$loop._flush();
+                    console.log(lines.cells[13].element.children[2].className);
+                    assert.ok(/ace_users_css/.test(lines.cells[13].element.children[3].className));
+                    // fold widget is not shown
+                    assert.equal(lines.cells[13].element.children[1].style.display, "none");
+    
+                    // After escape focus should be back to the gutter.
+                    emit(keys["escape"]);
+                    assert.equal(document.activeElement, editor.renderer.$gutter);
+    
+                    done();
+                }, 20);
+            }, 20);
+        },
+
+        "test: folding is kept consistent when custom widget is shown first and then hidden" : function(done) {
+            var editor = this.editor;
+            var value = "x {" + "\n".repeat(50) + "}\n";
+            value = value.repeat(50);
+            editor.session.setMode(new Mode());
+            editor.setValue(value, -1);
+            editor.setOption("enableKeyboardAccessibility", true);
+            editor.renderer.$loop._flush();
+    
+            var lines = editor.renderer.$gutterLayer.$lines;
+    
+            // Set focus to the gutter div.
+            editor.renderer.$gutter.focus();
+            assert.equal(document.activeElement, editor.renderer.$gutter);
+    
+            // Focus on the custom widget.
+            emit(keys["enter"]);
+            // Click the fold widget.
+            emit(keys["enter"]);
+            editor.renderer.$gutterLayer.showCustomWidget(0, {
+                className: "ace_users_css",
+                label: "Open_label",
+                title: "Open_title"
+            });
+            editor.renderer.$gutterLayer.hideCustomWidget(0);
+    
+            setTimeout(function() {
+                assert.equal(document.activeElement, lines.cells[0].element.childNodes[1]);
+    
+                setTimeout(function() {
+                    // Check that custom widget is hidden.
+                    editor.renderer.$loop._flush();
+                    assert.ok(/ace_users_css/.test(lines.cells[0].element.children[3].className));
+                    assert.equal(lines.cells[0].element.children[3].style.display, "none");
+                    assert.ok(/ace_closed/.test(lines.cells[0].element.children[1].className));
+    
+                    // After escape focus should be back to the gutter.
+                    emit(keys["escape"]);
+                    assert.equal(document.activeElement, editor.renderer.$gutter);
+    
+                    done();
+                }, 20);
+            }, 20);
+        },
+
+    tearDown : function() {
+        this.editor.destroy();
+        document.body.removeChild(this.editor.container);
+    }
+};
+
+if (typeof module !== "undefined" && module === require.main) {
+    require("asyncjs").test.testcase(module.exports).exec();
+}
diff --git a/types/ace-modules.d.ts b/types/ace-modules.d.ts
@@ -422,6 +422,30 @@ declare module "ace-code/src/layer/gutter" {
         getShowLineNumbers(): boolean;
         setShowFoldWidgets(show?: boolean): void;
         getShowFoldWidgets(): boolean;
+        /**
+         * Hides the fold widget/icon from a specific row in the gutter
+         * @param {number} row The row number from which to hide the fold icon
+         */
+        hideFoldWidget(row: number): void;
+        /**
+         * Shows the fold widget/icon from a specific row in the gutter
+         * @param {number} row The row number from which to show the fold icon
+         */
+        showFoldWidget(row: number): void;
+        /**
+         * Displays a custom widget for a specific row
+         * @param {number} row - The row number where the widget will be displayed
+         * @param {Object} options - Configuration options for the widget
+         * @param {string} options.className - CSS class name for styling the widget
+         * @param {string} options.label - Text label to display in the widget
+         * @param {string} options.title - Tooltip text for the widget
+         */
+        showCustomWidget(row: number, { className, label, title }: {
+            className: string;
+            label: string;
+            title: string;
+        }): void;
+        hideCustomWidget(row: any): void;
         getRegion(point: {
             x: number;
         }): "markers" | "foldWidgets";
@@ -3948,6 +3972,20 @@ declare module "ace-code/src/edit_session" {
          * @param {String} className The class to add
          **/
         addGutterDecoration(row: number, className: string): void;
+        /**
+         * Replaces the custom icon with the fold widget if present from a specific row in the gutter
+         * @param {number} row The row number for which to hide the custom icon
+         */
+        hideGutterCustomWidget(row: number): void;
+        /**
+         * Replaces the fold widget if present with the custom icon from a specific row in the gutter
+     * @param {number} row - The row number where the widget will be displayed
+     * @param {Object} options - Configuration options for the widget
+     * @param {string} options.className - CSS class name for styling the widget
+     * @param {string} options.label - Text label to display in the widget
+     * @param {string} options.title - Tooltip text for the widget
+     */
+        showGutterCustomWidget(row: number, attributes: any): void;
         /**
          * Removes `className` from the `row`.
          * @param {Number} row The row number

Original file line number	Diff line number	Diff line change
@@ -507,7 +507,7 @@ module.exports = `
`507`	`507`	`padding-right: 13px;`
`508`	`508`	`}`
`509`	`509`
`510`		`-.ace_fold-widget {`
	`510`	`+.ace_fold-widget, .ace_custom-widget {`
`511`	`511`	`box-sizing: border-box;`
`512`	`512`
`513`	`513`	`margin: 0 -12px 0 1px;`