feat(searchBox): ability to be non-instant

If `searchOnEnterKeyPressOnly` is set to true, the search is only triggered if ENTER is pressed.

 - Added some tests on even registration
 - Removed an outdated version of the searchbox that was at the root level of the widgets/ directory.
 - Updated jsdoc

Fix #458

Author: redox

docs/_includes/widget-jsdoc/searchBox.md

@@ -3,9 +3,12 @@
 |  <span class='attr-required'>`options.container`</span> | CSS Selector or DOMElement to insert the widget |
 |  <span class='attr-optional'>`options.placeholder`</span> | Input's placeholder |
 |  <span class='attr-optional'>`options.cssClasses`</span> | CSS classes to add |
+|  <span class='attr-optional'>`options.cssClasses.root`</span> | CSS class to add to the wrapping div (if wrapInput set to `true`) |
 |  <span class='attr-optional'>`options.cssClasses.input`</span> | CSS class to add to the input |
 |  <span class='attr-optional'>`options.cssClasses.poweredBy`</span> | CSS class to add to the poweredBy element |
-|  <span class='attr-optional'>`options.poweredBy`</span> | Show a powered by Algolia link below the input |
-|  <span class='attr-optional'>`options.autofocus`</span> | autofocus on the input |
+|  <span class='attr-optional'>`poweredBy`</span> | Show a powered by Algolia link below the input |
+|  <span class='attr-optional'>`wrapInput`</span> | Wrap the input in a div.ais-search-box |
+|  <span class='attr-optional'>`autofocus`</span> | autofocus on the input |
+|  <span class='attr-optional'>`searchOnEnterKeyPressOnly`</span> | If false, trigger the search once <Enter> is pressed only |
 
 <p class="attr-legend">* <span>Required</span></p>

widgets/search-box.js

@@ -32,6 +32,8 @@ describe('search-box()', () => {
     };
     helper = {
       on: sinon.spy(),
+      setQuery: sinon.spy(),
+      search: sinon.spy(),
       state: {
         query: ''
       }
@@ -166,6 +168,74 @@ describe('search-box()', () => {
     });
   });
 
+  context('keyup', () => {
+    let input;
+    beforeEach(() => {
+      container = document.createElement('div');
+      input = createHTMLNodeFromString('<input />');
+      input.addEventListener = sinon.spy();
+    });
+
+    context('instant search', () => {
+      beforeEach(() => {
+        widget = searchBox({container, autofocus: 'auto'});
+        widget.getInput = sinon.stub().returns(input);
+      });
+
+      it('performs the search on keyup', () => {
+        // Given
+        helper.state.query = 'foo';
+        // When
+        widget.init(initialState, helper);
+        // Then
+        expect(input.addEventListener.called).toEqual(true);
+        expect(input.addEventListener.args[0].length).toEqual(2);
+        expect(input.addEventListener.args[0][0]).toEqual('keyup');
+        let fn = input.addEventListener.args[0][1];
+        fn({});
+        expect(helper.setQuery.calledOnce).toBe(true);
+        expect(helper.search.calledOnce).toBe(true);
+      });
+    });
+
+    context('non-instant search', () => {
+      beforeEach(() => {
+        widget = searchBox({container, autofocus: 'auto', searchOnEnterKeyPressOnly: true});
+        widget.getInput = sinon.stub().returns(input);
+      });
+
+      it('performs the search on <ENTER>', () => {
+        // Given
+        helper.state.query = 'foo';
+        // When
+        widget.init(initialState, helper);
+        // Then
+        expect(input.addEventListener.called).toEqual(true);
+        expect(input.addEventListener.args[0].length).toEqual(2);
+        expect(input.addEventListener.args[0][0]).toEqual('keyup');
+        let fn = input.addEventListener.args[0][1];
+        fn({keyCode: 13});
+        expect(helper.setQuery.calledOnce).toBe(true);
+        expect(helper.search.calledOnce).toBe(true);
+      });
+
+      it('doesn\'t perform the search on keyup', () => {
+        // Given
+        helper.state.query = 'foo';
+        // When
+        widget.init(initialState, helper);
+        // Then
+        expect(input.addEventListener.called).toEqual(true);
+        expect(input.addEventListener.args[0].length).toEqual(2);
+        expect(input.addEventListener.args[0][0]).toEqual('keyup');
+        let fn = input.addEventListener.args[0][1];
+        fn({});
+        expect(helper.setQuery.calledOnce).toBe(true);
+        expect(helper.search.calledOnce).toBe(false);
+      });
+    });
+  });
+
   context('focus', () => {
     let input;
     beforeEach(() => {

widgets/search-box/__tests__/search-box-test.js

@@ -5,6 +5,8 @@ let forEach = require('lodash/collection/forEach');
 let bem = require('../../lib/utils').bemHelper('ais-search-box');
 let cx = require('classnames');
 
+const KEY_ENTER = 13;
+
 /**
  * Instantiate a searchbox
  * @param  {string|DOMElement} options.container CSS Selector or DOMElement to insert the widget
@@ -16,6 +18,7 @@ let cx = require('classnames');
  * @param  {boolean} [poweredBy=false] Show a powered by Algolia link below the input
  * @param  {boolean} [wrapInput=true] Wrap the input in a div.ais-search-box
  * @param  {boolean|string} [autofocus='auto'] autofocus on the input
+ * @param  {boolean} [searchOnEnterKeyPressOnly=false] If set, trigger the search once <Enter> is pressed only
  * @return {Object}
  */
 function searchBox({
@@ -24,10 +27,11 @@ function searchBox({
   cssClasses = {},
   poweredBy = false,
   wrapInput = true,
-  autofocus = 'auto'
+  autofocus = 'auto',
+  searchOnEnterKeyPressOnly = false
 }) {
   if (!container) {
-    throw new Error('Usage: searchBox({container[, placeholder, cssClasses.{input,poweredBy}, poweredBy, wrapInput, autofocus]})');
+    throw new Error('Usage: searchBox({container[, placeholder, cssClasses.{input,poweredBy}, poweredBy, wrapInput, autofocus, searchOnEnterKeyPressOnly]})');
   }
 
   container = utils.getContainerNode(container);
@@ -96,8 +100,11 @@ function searchBox({
 
       // Add all the needed attributes and listeners to the input
       this.addDefaultAttributesToInput(input, initialState.query);
-      input.addEventListener('keyup', () => {
-        helper.setQuery(input.value).search();
+      input.addEventListener('keyup', (e) => {
+        helper.setQuery(input.value);
+        if (!searchOnEnterKeyPressOnly || e.keyCode === KEY_ENTER) {
+          helper.search();
+        }
       });
 
       if (isInputTargeted) {