feat(ctrl-click): Enable Ctrl-Click on suggestions (#542)

* feat(ctrl-click): Enable Ctrl-Click on suggestions

This updates the underlying autocomplete.js to a version that passes
the selection context (click or keyboard) to the
`autocomplete:selected` event.

With the default `handleSelected, and in the case of a click, it will
do nothing (as each suggestion already being a `<a href>`, it will
already follow the link), but manually change the location for
keyboard navigation.

When a custom `handleSelected` is set though, default browser clicks
on suggestions are disabled and only `handleSelected` is called. This
is to keep backward compatibility with all the live websites that
might already use `handleSelected`.

* fix(test): Making sure it does not crash when no context is passed

docs/src/behavior.md

@@ -24,24 +24,34 @@ docsearch({
 
 ## `handleSelected`
 
-This method is called when a suggestion is selected. By default, DocSearch will
-redirect the browser to the results page at the related anchor, but you can
-override it to add your own behavior.
+This method is called when a suggestion is selected (either with a click or
+keyboard). By default, DocSearch will redirect the browser to the results page
+at the related anchor, but you can override it to add your own behavior.
 
-The method is called with three arguments:
+The method is called with the following arguments:
 
 - `input`, a reference to the search `input` element. It comes with the
   `.open()`, `.close()`, `.getVal()` and `.setVal()` methods.
 
-- `event`, the actual event triggering the selection. This can come from a click
-  or a keyboard navigation.
+- `event`, the actual event triggering the selection.
 
-- `suggestion`, the object representing the current selection.
+- `suggestion`, the object representing the current selection. Contains a `.url`
+  key representing the destination.
+
+- `datasetNumber`, this should always equal `1` as DocSearch is searching
+  into one dataset at a time. You can ignore this attribute.
+
+- `context`, additional information about the selection. Contains
+  a `.selectionMethod` key that can be either `click`, `enterKey`, `tabKey` or
+  `blur`, depending how the suggestion was selected.
 
 ```javascript
 docsearch({
   […],
-  handleSelected: function(input, event, suggestion) {
+  handleSelected: function(input, event, suggestion, datasetNumber, context) {
+    // Default implementation is as follow:
+    input.setVal('');
+    window.location.assign(suggestion.url);
   }
 });
 ```

package.json

@@ -76,7 +76,7 @@
   "peerDependencies": {},
   "dependencies": {
     "algoliasearch": "^3.24.5",
-    "autocomplete.js": "0.32.0",
+    "autocomplete.js": "0.33.0",
     "hogan.js": "^3.0.2",
     "request": "^2.87.0",
     "stack-utils": "^1.0.1",

scripts/playground.html

@@ -26,11 +26,13 @@
         apiKey: '25626fae796133dc1e734c6bcaaeac3c',
         indexName: 'docsearch',
         inputSelector: '#q',
-        // handleSelected(input, event, suggestion) {
-        //   console.info(input);
-        //   console.info(event);
-        //   console.info(suggestion);
-        // },
+        handleSelected(input, event, suggestion, datasetNumber, context) {
+          console.info(input);
+          console.info(event);
+          console.info(suggestion);
+          console.info(datasetNumber);
+          console.info(context);
+        },
         debug: true // Set debug to true if you want to inspect the dropdown
       });
     </script>

src/lib/DocSearch.js

@@ -78,8 +78,6 @@ class DocSearch {
     this.autocompleteOptions.cssClasses.prefix =
       this.autocompleteOptions.cssClasses.prefix || 'ds';
 
-    // eslint-disable-next-line no-param-reassign
-    handleSelected = handleSelected || this.handleSelected;
 
     this.isSimpleLayout = layout === 'simple';
 
@@ -101,19 +99,19 @@ class DocSearch {
       },
     ]);
 
-    // If user defined its own handleSelected, we prevent clicks on suggestions
-    // link to do anything
-    if (handleSelected) {
+    const customHandleSelected = handleSelected;
+    this.handleSelected = customHandleSelected || this.handleSelected;
+
+    // We prevent default link clicking if a custom handleSelected is defined
+    if (customHandleSelected) {
       $('.algolia-autocomplete').on('click', '.ds-suggestions a', event => {
         event.preventDefault();
       });
     }
 
-    // Click on suggestions will follow the link, but keyboard navigation still
-    // need the handleSelected
     this.autocomplete.on(
       'autocomplete:selected',
-      handleSelected.bind(null, this.autocomplete.autocomplete)
+      this.handleSelected.bind(null, this.autocomplete.autocomplete)
     );
 
     this.autocomplete.on(
@@ -324,7 +322,14 @@ class DocSearch {
     return suggestion => template.render(suggestion);
   }
 
-  handleSelected(input, event, suggestion) {
+  handleSelected(input, event, suggestion, datasetNumber, context = {}) {
+    // Do nothing if click on the suggestion, as it's already a <a href>, the
+    // browser will take care of it. This allow Ctrl-Clicking on results and not
+    // having the main window being redirected as well
+    if (context.selectionMethod === 'click') {
+      return;
+    }
+
     input.setVal('');
     window.location.assign(suggestion.url);
   }

yarn.lock

@@ -541,10 +541,10 @@ atob@^2.1.1:
   resolved "https://registry.yarnpkg.com/atob/-/atob-2.1.1.tgz#ae2d5a729477f289d60dd7f96a6314a22dd6c22a"
   integrity sha1-ri1acpR38onWDdf5amMUoi3Wwio=
 
-autocomplete.js@0.32.0:
-  version "0.32.0"
-  resolved "https://registry.yarnpkg.com/autocomplete.js/-/autocomplete.js-0.32.0.tgz#a00eab44dcb9e573ebd8bb3178e7fe67466cd4f1"
-  integrity sha512-GYGmOo0r2wLgUEYE5J9z9OSLb8e0SAicgDR1M1pHOvwQ0Hc1SLHR0EqjDhl+lhl01cYq2d7lLbsgRmaizgLqrA==
+autocomplete.js@0.33.0:
+  version "0.33.0"
+  resolved "https://registry.yarnpkg.com/autocomplete.js/-/autocomplete.js-0.33.0.tgz#33d460367e2e7b6c2fe424353d955e022fe4594c"
+  integrity sha512-J0F7BkPhYwXvfs8Skp6v2e2IHYv0SL8INyHYwb7nUpvKHr96g6zS8RNEFGEfEuO3ND+XUsesEMM59LlwQoLfoA==
   dependencies:
     immediate "^3.2.3"