context-aware hinter code

Author: kammeows

client/modules/IDE/components/Editor/index.jsx

@@ -73,6 +73,8 @@ import { EditorContainer, EditorHolder } from './MobileEditor';
 import { FolderIcon } from '../../../../common/icons';
 import IconButton from '../../../../common/IconButton';
 
+import contextAwareHinter from '../contextAwareHinter';
+
 emmet(CodeMirror);
 
 window.JSHINT = JSHINT;
@@ -462,22 +464,27 @@ class Editor extends React.Component {
       // JavaScript
       CodeMirror.showHint(
         _cm,
-        () => {
-          const c = _cm.getCursor();
-          const token = _cm.getTokenAt(c);
-
-          const hints = this.hinter
-            .search(token.string)
-            .filter((h) => h.item.text[0] === token.string[0]);
-
-          return {
-            list: hints,
-            from: CodeMirror.Pos(c.line, token.start),
-            to: CodeMirror.Pos(c.line, c.ch)
-          };
-        },
+        (cm, options) => contextAwareHinter(cm, { hinter: this.hinter }),
         hintOptions
       );
+      // CodeMirror.showHint(
+      //   _cm,
+      //   () => {
+      //     const c = _cm.getCursor();
+      //     const token = _cm.getTokenAt(c);
+
+      //     const hints = this.hinter
+      //       .search(token.string)
+      //       .filter((h) => h.item.text[0] === token.string[0]);
+
+      //     return {
+      //       list: hints,
+      //       from: CodeMirror.Pos(c.line, token.start),
+      //       to: CodeMirror.Pos(c.line, c.ch)
+      //     };
+      //   },
+      //   hintOptions
+      // );
     } else if (_cm.options.mode === 'css') {
       // CSS
       CodeMirror.showHint(_cm, CodeMirror.hint.css, hintOptions);

client/modules/IDE/components/show-hint.js

@@ -7,6 +7,11 @@
 
 // declare global: DOMRect
 
+// The first function (mod) is a wrapper to support different JavaScript environments.
+// The second function (inside) contains the actual implementation.
+import parseCode from './parseCode';
+import CodeMirror from 'codemirror';
+
 (function (mod) {
   if (typeof exports == 'object' && typeof module == 'object')
     // CommonJS
@@ -16,6 +21,8 @@
     define(['codemirror'], mod);
   // Plain browser env
   else mod(CodeMirror);
+
+  // This part uptill here makes the code compatible with multiple JavaScript environments, so it can run in different places
 })(function (CodeMirror) {
   'use strict';
 
@@ -25,55 +32,67 @@
   // This is the old interface, kept around for now to stay
   // backwards-compatible.
   CodeMirror.showHint = function (cm, getHints, options) {
-    if (!getHints) return cm.showHint(options);
+    console.log('showhint was called: ', getHints, options);
+    if (!getHints) return cm.showHint(options); // if not getHints function passed, it assumes youre using the newer interface
+    // restructured options to call the new c.showHint() method
     if (options && options.async) getHints.async = true;
     var newOpts = { hint: getHints };
     if (options) for (var prop in options) newOpts[prop] = options[prop];
+    console.log('newopts: ', newOpts);
+    const context = parseCode(cm);
+    console.log('Cursor context =', context);
     return cm.showHint(newOpts);
   };
 
+  // this adds a method called showHint to every cm editor instance (editor.showHint())
   CodeMirror.defineExtension('showHint', function (options) {
     options = parseOptions(this, this.getCursor('start'), options);
     var selections = this.listSelections();
+    console.log('selections are: ', selections);
     if (selections.length > 1) return;
     // By default, don't allow completion when something is selected.
     // A hint function can have a `supportsSelection` property to
     // indicate that it can handle selections.
     if (this.somethingSelected()) {
       if (!options.hint.supportsSelection) return;
       // Don't try with cross-line selections
+      // if selection spans multiple lines, bail out
       for (var i = 0; i < selections.length; i++)
         if (selections[i].head.line != selections[i].anchor.line) return;
     }
 
-    if (this.state.completionActive) this.state.completionActive.close();
+    if (this.state.completionActive) this.state.completionActive.close(); // close an already active autocomplete session if active
+    // create a new completion object and saves it to this.state.completionActive
     var completion = (this.state.completionActive = new Completion(
       this,
       options
     ));
-    if (!completion.options.hint) return;
+    if (!completion.options.hint) return; // safety check to ensure hint is valid
 
-    CodeMirror.signal(this, 'startCompletion', this);
+    CodeMirror.signal(this, 'startCompletion', this); // emits a signal; fires a startCompletion event on editor instance
     completion.update(true);
   });
 
   CodeMirror.defineExtension('closeHint', function () {
     if (this.state.completionActive) this.state.completionActive.close();
   });
 
+  // defines a constructor function
   function Completion(cm, options) {
     this.cm = cm;
     this.options = options;
-    this.widget = null;
+    this.widget = null; // will hold a reference to the dropdown menu that shows suggestions
     this.debounce = 0;
     this.tick = 0;
-    this.startPos = this.cm.getCursor('start');
+    this.startPos = this.cm.getCursor('start'); // startPos is a {line,ch} object used to remember where hinting started
+    // startLen is the len of the line minus length of any selected text
     this.startLen =
       this.cm.getLine(this.startPos.line).length -
       this.cm.getSelection().length;
 
     if (this.options.updateOnCursorActivity) {
-      var self = this;
+      var self = this; // stores ref to this as self so it can be accessed inside the nested function
+      // adds an event listener to the editor; called when the cursor moves
       cm.on(
         'cursorActivity',
         (this.activityFunc = function () {
@@ -95,12 +114,14 @@
       if (!this.active()) return;
       this.cm.state.completionActive = null;
       this.tick = null;
+      // removes the current activity listener
       if (this.options.updateOnCursorActivity) {
         this.cm.off('cursorActivity', this.activityFunc);
       }
-
+      // signals and removes the widget
       if (this.widget && this.data) CodeMirror.signal(this.data, 'close');
       if (this.widget) this.widget.close();
+      // emits a completition end event
       CodeMirror.signal(this.cm, 'endCompletion', this.cm);
     },
 
@@ -109,6 +130,7 @@
     },
 
     pick: function (data, i) {
+      // selects an item from the suggestion list
       var completion = data.list[i],
         self = this;
       this.cm.operation(function () {
@@ -120,15 +142,18 @@
             completion.to || data.to,
             'complete'
           );
+        // signals that a hint was picked and scrolls to it
         CodeMirror.signal(data, 'pick', completion);
         self.cm.scrollIntoView();
       });
+      // closes widget if closeOnPick is enabled
       if (this.options.closeOnPick) {
         this.close();
       }
     },
 
     cursorActivity: function () {
+      // if a debounce is scheduled, cancel it to avoid outdated updates
       if (this.debounce) {
         cancelAnimationFrame(this.debounce);
         this.debounce = 0;
@@ -149,6 +174,7 @@
         !pos.ch ||
         this.options.closeCharacters.test(line.charAt(pos.ch - 1))
       ) {
+        console.log('this.close called');
         this.close();
       } else {
         var self = this;
@@ -192,6 +218,7 @@
   function parseOptions(cm, pos, options) {
     var editor = cm.options.hintOptions;
     var out = {};
+    // copies all default hint settings into out
     for (var prop in defaultOptions) out[prop] = defaultOptions[prop];
     if (editor)
       for (var prop in editor)
@@ -200,14 +227,16 @@
       for (var prop in options)
         if (options[prop] !== undefined) out[prop] = options[prop];
     if (out.hint.resolve) out.hint = out.hint.resolve(cm, pos);
+    console.log('out is ', out);
     return out;
   }
-
+  // extracts the visible text from a completion entry
   function getText(completion) {
     if (typeof completion === 'string') return completion;
     else return completion.item.text;
   }
 
+  // builds a key mapping object to define keyboard behavior for autocomplete
   function buildKeyMap(completion, handle) {
     var baseMap = {
       Up: function () {
@@ -232,7 +261,7 @@
       Tab: handle.pick,
       Esc: handle.close
     };
-
+    // checks if the user is on macOS and adds shortcuts accordingly
     var mac = /Mac/.test(navigator.platform);
 
     if (mac) {
@@ -244,6 +273,7 @@
       };
     }
 
+    // user defined custom key bindings
     var custom = completion.options.customKeys;
     var ourMap = custom ? {} : baseMap;
     function addBinding(key, val) {
@@ -257,6 +287,7 @@
       else bound = val;
       ourMap[key] = bound;
     }
+    // apply all custom key bindings and extraKeys
     if (custom)
       for (var key in custom)
         if (custom.hasOwnProperty(key)) addBinding(key, custom[key]);
@@ -267,15 +298,20 @@
     return ourMap;
   }
 
+  // hintsElement is the parent for hints and el is the clicked element within that container
   function getHintElement(hintsElement, el) {
+    console.log('el is ', el);
     while (el && el != hintsElement) {
-      if (el.nodeName.toUpperCase() === 'LI' && el.parentNode == hintsElement)
+      if (el.nodeName.toUpperCase() === 'LI' && el.parentNode == hintsElement) {
+        console.log('new el is ', el);
         return el;
+      }
       el = el.parentNode;
     }
   }
 
   function displayHint(name, type, p5) {
+    console.log('name is', name, type, p5);
     return `<p class="${type}-item">\
 <span class="${type}-name hint-name">${name}</span>\
 <span class="hint-hidden">, </span>\
@@ -293,7 +329,9 @@ ${
   }
 
   function getInlineHintSuggestion(focus, tokenLength) {
+    console.log('the focus is: ', focus, tokenLength);
     const suggestionItem = focus.item;
+    // builds the remainder of the suggestion excluding what user already typed
     const baseCompletion = `<span class="inline-hinter-suggestion">${suggestionItem.text.slice(
       tokenLength
     )}</span>`;
@@ -310,6 +348,7 @@ ${
     );
   }
 
+  // clears existing inline hint (like the part is suggested)
   function removeInlineHint(cm) {
     if (cm.state.inlineHint) {
       cm.state.inlineHint.clear();
@@ -341,7 +380,12 @@ ${
     }
   }
 
+  // defines the autocomplete dropdown ui
+  // completition = the autocomplete context having cm and options
+  // data = object with the list of suggestions
   function Widget(completion, data) {
+    console.log('widget completetition= ', completion);
+    console.log('widget data= ', data);
     this.id = 'cm-complete-' + Math.floor(Math.random(1e6));
     this.completion = completion;
     this.data = data;