Fix bug where suggestions could never be set if falsy (#48)

Also adds test coverage for updateSuggestions and hinting.

Author: josephschmitt

README.md

@@ -163,7 +163,14 @@ displayed.
 To display a hint to the user in addition to suggestions, resolve the promise with an object that
 has keys for `hint` and `suggestions`: `{hint: 'My hint', suggestions: [...]}`. A hint is displayed
 to the right of the text that has been input by the user. Pressing RIGHT on the keyboard replaces
-the input text query with the hint.
+the input text query with the hint. The hint should include the entirety of the query, plus whatever
+else you want to hint with. When displayed, only the addition to the query is shown as a hint, but
+if the user presses RIGHT to complete it, it will use the entirety of the hint provided. For
+example, if the query is 'my query' and you want to hinted text to display ' is awesome', then you
+should pass 'my query is awesome' as the hint. However, if you want the completed hint to be
+formatted as 'My Query is Awesome', you should set that as the hint. When hinted, it will be
+displayed as 'my query is Awesome', but when completed via RIGHT on the keyboard, it will replace
+the query with the submitted formatting: 'My Query is Awesome'.
 - `ngModel {Any}` _(Required)_: This is a one-way binding to the ngModel for the Omnibox. When the
 `multiple` option is set to `true`, then the `ngModel` should be an array. Each item in the array
 will be populated with choices from the objects passed via the `source` function. If the `multiple`

spec/tests/angularComponent/ngcOmniboxControllerSpec.js

@@ -18,6 +18,51 @@ describe('ngcOmnibox.angularComponent.ngcOmniboxController', () => {
     omniboxController.isSelectable = () => {};
   });
 
+  describe('when populating suggestions via the source function', () => {
+    it('it should empty out the suggestions when resolving to a falsy value', (done, fail) => {
+      omniboxController.query = 'my query';
+      omniboxController.suggestions = ['suggestion 1', 'suggestion 2'];
+      omniboxController.source = () => Promise.resolve(null);
+      omniboxController.updateSuggestions().then(() => {
+        expect(omniboxController.suggestions).toBe(null);
+      }).then(done, fail);
+    });
+
+    it('it should set the suggestions when resolving to an Array', (done, fail) => {
+      omniboxController.query = 'my query';
+      omniboxController.suggestions = ['suggestion 1', 'suggestion 2'];
+      omniboxController.source = () => Promise.resolve(['new suggestion 1', 'new suggestion 2']);
+      omniboxController.updateSuggestions().then(() => {
+        expect(omniboxController.suggestions.join(',')).toBe('new suggestion 1,new suggestion 2');
+      }).then(done, fail);
+    });
+
+    it('it should throw an error when resolving to a truthy, non-Array value', (done, fail) => {
+      omniboxController.query = 'my query';
+      omniboxController.suggestions = ['suggestion 1', 'suggestion 2'];
+      omniboxController.source = () => Promise.resolve(true);
+      omniboxController.updateSuggestions().then(fail, (e) => {
+        expect(e.message).toBe('Suggestions must be an Array');
+      }).then(done, fail);
+    });
+
+    it('should support resolving suggestions and hints', (done, fail) => {
+      omniboxController.query = 'my query';
+      omniboxController.suggestions = [];
+      omniboxController.source = () => {
+        return Promise.resolve({
+          suggestions: ['new suggestion 1', 'new suggestion 2'],
+          hint: 'My Query is Awesome'
+        });
+      };
+      omniboxController.updateSuggestions().then(() => {
+        expect(omniboxController.suggestions.join(',')).toBe('new suggestion 1,new suggestion 2');
+        expect(omniboxController.hint).toBe('my query is Awesome');
+        expect(omniboxController.fullHint).toBe('My Query is Awesome');
+      }).then(done, fail);
+    });
+  });
+
   describe('when determining if there are suggestions', () => {
     it('should return false for falsy values', () => {
       omniboxController.suggestions = false;
@@ -30,18 +75,13 @@ describe('ngcOmnibox.angularComponent.ngcOmniboxController', () => {
       expect(omniboxController.hasSuggestions).toBe(false);
     });
 
-    it('should return false for suggestions that aren\'t an Array', () => {
-      omniboxController.suggestions = 'false';
-      expect(omniboxController.hasSuggestions).toBe(false);
-
-      omniboxController.suggestions = true;
-      expect(omniboxController.hasSuggestions).toBe(false);
-
-      omniboxController.suggestions = 100;
-      expect(omniboxController.hasSuggestions).toBe(false);
+    it('should throw an Error for suggestions that aren\'t an Array', () => {
+      const errorMsg = 'Suggestions must be an Array';
 
-      omniboxController.suggestions = {test: 'me'};
-      expect(omniboxController.hasSuggestions).toBe(false);
+      expect(() => omniboxController.suggestions = 'false').toThrowError(errorMsg);
+      expect(() => omniboxController.suggestions = true).toThrowError(errorMsg);
+      expect(() => omniboxController.suggestions = 100).toThrowError(errorMsg);
+      expect(() => omniboxController.suggestions = {test: 'me'}).toThrowError(errorMsg);
     });
 
     it('should return false for empty Arrays', () => {

src/angularComponent/ngcOmniboxController.js

@@ -77,9 +77,13 @@ export default class NgcOmniboxController {
   }
 
   set suggestions(suggestions) {
-    if (Array.isArray(suggestions)) {
+    if (!suggestions) {
+      this._suggestions = null;
+    } else if (Array.isArray(suggestions)) {
       this._suggestions = Array.prototype.slice.apply(suggestions);
       this._buildSuggestionsUiList();
+    } else {
+      throw new Error('Suggestions must be an Array');
     }
 
     this.hasSuggestions = Array.isArray(suggestions) && !!suggestions.length;
@@ -430,12 +434,56 @@ export default class NgcOmniboxController {
     return this._shouldShowSuggestions;
   }
 
+  /**
+   * Updates the list of suggestions based on the current query and the source function.
+   *
+   * @returns {Promise} -- Resolved after the suggestions have been updated
+   */
+  updateSuggestions() {
+    this._suggestionsUiList.length = 0;
+    this.hint = null;
+
+    this.highlightedIndex = -1; // Forcibly select nothing
+    this._showLoading();
+    this.hideSuggestions = false;
+
+    const promise = this.source({query: this.query, suggestions: this.suggestions});
+    this._sourceFunctionPromise = promise;
+
+    return promise.then((suggestions) => {
+      // Bail out if the promise has changed
+      if (promise !== this._sourceFunctionPromise) {
+        return;
+      }
+
+      let hint;
+      if (suggestions && !Array.isArray(suggestions) && typeof suggestions === 'object') {
+        hint = suggestions.hint;
+        suggestions = suggestions.suggestions;
+      }
+
+      this.suggestions = suggestions;
+
+      if (hint) {
+        // Hint with just the part of the hint that isn't the query
+        this.hint = this.query + hint.slice(this.query.length, hint.length);
+        this.fullHint = hint; // Store this for completion of the hint
+      }
+
+      this._hideLoading();
+
+      if (this.requireMatch) {
+        this.highlightNextSuggestion();
+      }
+    });
+  }
+
   onInputChange() {
     if (!this.query) {
       this.hideSuggestions = true;
       this.hint = null;
     } else {
-      this._updateSuggestions();
+      this.updateSuggestions();
     }
   }
 
@@ -472,7 +520,7 @@ export default class NgcOmniboxController {
 
       if (this.hint) {
         if (keyCode === KEY.RIGHT && this.selectionEndKeyDown === inputLength) {
-          this.query = this._fullHint;
+          this.query = this.fullHint;
           this.onInputChange();
         } else if (keyCode === KEY.ESC) {
           this.hint = null;
@@ -504,7 +552,7 @@ export default class NgcOmniboxController {
         }
       }
     } else if (keyCode === KEY.DOWN) {
-      this._updateSuggestions();
+      this.updateSuggestions();
     }
   }
 
@@ -546,51 +594,6 @@ export default class NgcOmniboxController {
     }
   }
 
-  _updateSuggestions() {
-    this._suggestionsUiList.length = 0;
-    this.hint = null;
-
-    this.highlightedIndex = -1; // Forcibly select nothing
-    this._showLoading();
-    this.hideSuggestions = false;
-
-    const promise = this.source({query: this.query, suggestions: this.suggestions});
-    this._sourceFunctionPromise = promise;
-
-    promise.then((suggestions) => {
-      // Bail out if the promise has changed
-      if (promise !== this._sourceFunctionPromise) {
-        return;
-      }
-
-      let hint;
-      if (typeof suggestions === 'object') {
-        hint = suggestions.hint;
-        suggestions = suggestions.suggestions;
-      }
-
-      if (!suggestions) {
-        this.suggestions = null;
-      } else if (Array.isArray(suggestions)) {
-        this.suggestions = suggestions;
-      } else {
-        throw new Error('Suggestions must be an Array');
-      }
-
-      if (hint) {
-        // Hint with just the part of the hint that isn't the query
-        this.hint = this.query + hint.slice(this.query.length, hint.length);
-        this._fullHint = hint; // Store this for completion of the hint
-      }
-
-      this._hideLoading();
-
-      if (this.requireMatch) {
-        this.highlightNextSuggestion();
-      }
-    });
-  }
-
   _showLoading() {
     this.isLoading = true;