Improve types for internal development

src/ace.js

@@ -28,7 +28,7 @@ exports.config = require("./config");
 
 /**
  * Embeds the Ace editor into the DOM, at the element provided by `el`.
- * @param {String | HTMLElement & {env?, value?}} el Either the id of an element, or the element itself
+ * @param {String | HTMLElement & {env?: any, value?: any} | null} [el] Either the id of an element, or the element itself
  * @param {Object } [options] Options for the editor
  * @returns {Editor}
  **/
@@ -86,4 +86,5 @@ exports.Editor = Editor;
 exports.EditSession = EditSession;
 exports.UndoManager = UndoManager;
 exports.VirtualRenderer = Renderer;
-exports.version = exports.config.version;
+var version = exports.config.version;
+exports.version = version;

src/anchor.js

@@ -25,7 +25,7 @@ class Anchor {
         else
             this.setPosition(row, column);
     }
-    
+
     /**
      * Returns an object identifying the `row` and `column` position of the current anchor.
      * @returns {import("../ace-internal").Ace.Point}
@@ -42,18 +42,19 @@ class Anchor {
     getDocument() {
         return this.document;
     }
-    
+
     /**
      * Internal function called when `"change"` event fired.
      * @param {import("../ace-internal").Ace.Delta} delta
+     * @internal
      */
     onChange(delta) {
         if (delta.start.row == delta.end.row && delta.start.row != this.row)
             return;
 
         if (delta.start.row > this.row)
             return;
-            
+
         var point = $getTransformedPoint(delta, {row: this.row, column: this.column}, this.$insertRight);
         this.setPosition(point.row, point.column, true);
     }

src/autocomplete.js

@@ -3,6 +3,7 @@
  * @typedef {import("./editor").Editor} Editor
  * @typedef {import("../ace-internal").Ace.CompletionProviderOptions} CompletionProviderOptions
  * @typedef {import("../ace-internal").Ace.CompletionOptions} CompletionOptions
+ * @typedef {import("../ace-internal").Ace.Position} Position
  */
 var HashHandler = require("./keyboard/hash_handler").HashHandler;
 var AcePopup = require("./autocomplete/popup").AcePopup;
@@ -31,7 +32,7 @@
  * @property {string} [command] - A command to be executed after the completion is inserted (experimental)
  * @property {string} [snippet] - a text snippet that would be inserted when the completion is selected
  * @property {string} [value] - The text that would be inserted when selecting this completion.
- * @property {import("../ace-internal").Ace.Completer & {insertMatch:(editor: Editor, data: Completion) => void}} [completer]
+ * @property {import("../ace-internal").Ace.Completer} [completer]
  * @property {boolean} [hideInlinePreview]
  * @export
  */
@@ -76,10 +77,11 @@
         this.keyboardHandler.bindKeys(this.commands);
         this.parentNode = null;
         this.setSelectOnHover = false;
+        /**@private*/
         this.hasSeen = new Set();
 
         /**
-         *  @property {Boolean} showLoadingState - A boolean indicating whether the loading states of the Autocompletion should be shown to the end-user. If enabled 
+         *  @property {Boolean} showLoadingState - A boolean indicating whether the loading states of the Autocompletion should be shown to the end-user. If enabled
          * it shows a loading indicator on the popup while autocomplete is loading.
          * 
          * Experimental: This visualisation is not yet considered stable and might change in the future.
@@ -255,6 +257,10 @@
         });
         this.$elements = null;
     }
+
+    /**
+     * @internal
+     */
     onLayoutChange() {
         if (!this.popup.isOpen) return this.unObserveLayoutChanges();
         this.$updatePopupPosition();
@@ -470,7 +476,7 @@
     /**
      * This is the entry point for the autocompletion class, triggers the actions which collect and display suggestions
      * @param {Editor} editor
-     * @param {CompletionOptions} options
+     * @param {CompletionOptions} [options]
      */
     showPopup(editor, options) {
         if (this.editor)
@@ -493,6 +499,11 @@
         this.updateCompletions(false, options);
     }
 
+    /**
+     *
+     * @param {{pos: Position, prefix: string}} [initialPosition]
+     * @return {CompletionProvider}
+     */
     getCompletionProvider(initialPosition) {
         if (!this.completionProvider)
             this.completionProvider = new CompletionProvider(initialPosition);
@@ -510,7 +521,7 @@
 
     /**
      * @param {boolean} keepPopupPosition
-     * @param {CompletionOptions} options
+     * @param {CompletionOptions} [options]
      */
     updateCompletions(keepPopupPosition, options) {
         if (keepPopupPosition && this.base && this.completions) {
@@ -705,7 +716,11 @@
         if (el.parentNode)
             el.parentNode.removeChild(el);
     }
-
+
+    /**
+     * @param e
+     * @internal
+     */
     onTooltipClick(e) {
         var a = e.target;
         while (a && a != this.tooltipNode) {
@@ -733,6 +748,30 @@
         this.inlineRenderer = this.popup = this.editor = null;
     }
 
+    /**
+     * @param {Editor} editor
+     * @return {Autocomplete}
+     */
+    static for(editor) {
+        if (editor.completer instanceof Autocomplete) {
+            return editor.completer;
+        }
+        if (editor.completer) {
+            editor.completer.destroy();
+            editor.completer = null;
+        }
+        if (config.get("sharedPopups")) {
+            if (!Autocomplete["$sharedInstance"])
+                Autocomplete["$sharedInstance"] = new Autocomplete();
+            editor.completer = Autocomplete["$sharedInstance"];
+        } else {
+            editor.completer = new Autocomplete();
+            editor.once("destroy", destroyCompleter);
+        }
+        // @ts-expect-error
+        return editor.completer;
+    }
+
 }
 
 Autocomplete.prototype.commands = {
@@ -762,26 +801,6 @@
     "PageDown": function(editor) { editor.completer.popup.gotoPageDown(); }
 };
 
-
-Autocomplete.for = function(editor) {
-    if (editor.completer instanceof Autocomplete) {
-        return editor.completer;
-    }
-    if (editor.completer) {
-        editor.completer.destroy();
-        editor.completer = null;
-    }
-    if (config.get("sharedPopups")) {
-        if (!Autocomplete["$sharedInstance"])
-            Autocomplete["$sharedInstance"] = new Autocomplete();
-        editor.completer = Autocomplete["$sharedInstance"];
-    } else {
-        editor.completer = new Autocomplete();
-        editor.once("destroy", destroyCompleter);
-    }
-    return editor.completer;
-};
-
 Autocomplete.startCommand = {
     name: "startAutocomplete",
     exec: function(editor, options) {
@@ -803,7 +822,7 @@
 
 
     /**
-     * @param {{pos: import("../ace-internal").Ace.Position, prefix: string}} initialPosition
+     * @param {{pos: Position, prefix: string}} [initialPosition]
      */
     constructor(initialPosition) {
         this.initialPosition = initialPosition;

src/bidihandler.js

@@ -39,7 +39,7 @@
         this.isMoveLeftOperation = false;
         this.seenBidi = bidiRE.test(session.getValue());
     }
-    
+
     /**
      * Returns 'true' if row contains Bidi characters, in such case
      * creates Bidi map to be used in operations related to selection
@@ -59,13 +59,17 @@
         return this.bidiMap.bidiLevels;
     }
 
+    /**
+     * @param {import("../ace-internal").Ace.Delta} delta
+     * @internal
+     */
     onChange(delta) {
         if (!this.seenBidi) {
             if (delta.action == "insert" && bidiRE.test(delta.lines.join("\n"))) {
                 this.seenBidi = true;
                 this.currentRow = null;
             }
-        } 
+        }
         else {
             this.currentRow = null;
         }
@@ -106,7 +110,7 @@
     updateRowLine(docRow, splitIndex) {
         if (docRow === undefined)
             docRow = this.getDocumentRow();
-            
+
         var isLastRow = (docRow === this.session.getLength() - 1),
             endOfLine = isLastRow ? this.EOF : this.EOL;
 
@@ -136,7 +140,7 @@
         } else {
             this.line += this.showInvisibles ? endOfLine : bidiUtil.DOT;
         }
-            
+
         /* replace tab and wide characters by commensurate spaces */
         var session = this.session, shift = 0, size;
         this.line = this.line.replace(/\t|[\u1100-\u2029, \u202F-\uFFE6]/g, function(ch, i){
@@ -153,7 +157,7 @@
             this.rtlLineOffset = this.contentWidth - this.fontMetrics.$main.getBoundingClientRect().width;
         }
     }
-    
+
     updateBidiMap() {
         var textCharTypes = [];
         if (bidiUtil.hasBidiCharacters(this.line, textCharTypes) || this.isRtlDir) {
@@ -197,7 +201,7 @@
     }
 
     setEolChar(eolChar) {
-        this.EOL = eolChar; 
+        this.EOL = eolChar;
     }
 
     setContentWidth(width) {
@@ -209,11 +213,11 @@
         if (row != undefined)
             return (this.session.getLine(row).charAt(0) == this.RLE);
         else
-            return this.isRtlDir; 
+            return this.isRtlDir;
     }
 
     setRtlDirection(editor, isRtlDir) {
-        var cursor = editor.getCursorPosition(); 
+        var cursor = editor.getCursorPosition();
         for (var row = editor.selection.getSelectionAnchor().row; row <= cursor.row; row++) {
             if (!isRtlDir && editor.session.getLine(row).charAt(0) === editor.session.$bidiHandler.RLE)
                 editor.session.doc.removeInLine(row, 0, 1);
@@ -238,7 +242,7 @@
 
         if (!this.session.getOverwrite() && col <= leftBoundary && levels[visualIdx] % 2 !== 0)
             visualIdx++;
-            
+
         for (var i = 0; i < visualIdx; i++) {
             left += this.charWidths[levels[i]];
         }
@@ -266,7 +270,7 @@
         var map = this.bidiMap, levels = map.bidiLevels, level, selections = [], offset = 0,
             selColMin = Math.min(startCol, endCol) - this.wrapIndent, selColMax = Math.max(startCol, endCol) - this.wrapIndent,
                 isSelected = false, isSelectedPrev = false, selectionStart = 0;
-            
+
         if (this.wrapIndent)
             offset += this.isRtlDir ? (-1 * this.wrapOffset) : this.wrapOffset;
 
@@ -311,7 +315,7 @@
 
         if (this.wrapIndent)
            posX -= this.isRtlDir ? (-1 * this.wrapOffset) : this.wrapOffset;
-    
+
         while(posX > offset + charWidth/2) {
             offset += charWidth;
             if(visualIdx === levels.length - 1) {
@@ -321,7 +325,7 @@
             }
             charWidth = this.charWidths[levels[++visualIdx]];
         }
-    
+
         if (visualIdx > 0 && (levels[visualIdx - 1] % 2 !== 0) && (levels[visualIdx] % 2 === 0)){
         /* Bidi character on the left and None Bidi character on the right */
             if(posX < offset)

src/config.js

@@ -6,6 +6,7 @@ var AppConfig = require("./lib/app_config").AppConfig;
 
 module.exports = exports = new AppConfig();
 
+/** @type {import("../ace-internal").Ace.ConfigOptions} */
 var options = {
     packaged: false,
     workerPath: null,
@@ -20,8 +21,9 @@ var options = {
 };
 
 /**
- * @param {string} key
- * @return {*}
+ * @template {keyof import("../ace-internal").Ace.ConfigOptions} K
+ * @param {K} key - The key of the config option to retrieve.
+ * @returns {import("../ace-internal").Ace.ConfigOptions[K]} - The value of the config option.
  */
 exports.get = function(key) {
     if (!options.hasOwnProperty(key))
@@ -30,8 +32,9 @@ exports.get = function(key) {
 };
 
 /**
- * @param {string} key
- * @param value
+ * @template {keyof import("../ace-internal").Ace.ConfigOptions} K
+ * @param {K} key
+ * @param {import("../ace-internal").Ace.ConfigOptions[K]} value
  */
 exports.set = function(key, value) {
     if (options.hasOwnProperty(key))
@@ -42,7 +45,7 @@ exports.set = function(key, value) {
         dom.useStrictCSP(value);
 };
 /**
- * @return {{[key: string]: any}}
+ * @return {import("../ace-internal").Ace.ConfigOptions}
  */
 exports.all = function() {
     return lang.copyObject(options);
@@ -100,9 +103,6 @@ var loader = function(moduleName, cb) {
     console.error("loader is not configured");
 };
 var customLoader;
-/**
- * @param {(moduleName: string, afterLoad: (err: Error | null, module: unknown) => void) => void}cb
- */
 exports.setLoader = function(cb) {
     customLoader = cb;
 };