📝 docs: add docs for hooks config option

Author: niketpathak

README.md

@@ -128,6 +128,7 @@ You can pass the following config options to `typeahead-standalone`:
 |`tokenizer?: (words: string) => string[]`|The tokenizer function is used to split the search query and the search data by a given character(s). This function is useful when you wish to search hypenated-words or words with a certain prefix/suffix |words are split by space characters (new line, tab, spaces)|
 |`listScrollOptions?: ScrollIntoViewOptions`| Allows fine control over the scroll behaviour for a large list of suggestions that needs scrolling. These options are passed to the `scrollIntoView()` function. [MDN Ref](https://developer.mozilla.org/docs/Web/API/Element/scrollIntoView)  | `{ block: "nearest", inline: "nearest", behaviour: "auto"}`|
 |`retainFocus`| This parameter is useful to control the focus on pressing the "Tab" key when the list of suggestions is open. If enabled, it selects the highlighted option & then returns the focus to the search input. If disabled, pressing "Tab" will select the highlighted option & take the focus away to the next focussable item in your form  | `true`|
+|`hooks`| The hooks config option has currently has 1 hook available `updateHits: (resultSet) => resultSet` which is executed just before the search results are displayed to the user & can be used to override the search results returned by the search index. (useful for custom sorting, filtering, adding or removing results. Note that that this hook is an async function allowing you to make AJAX requests to fetch new results if needed) | undefined |
 
 ---
 

docs/index.html

@@ -121,6 +121,7 @@ <h5 class="center">
               <li><a href="#config?id=tokenizer" title="tokenizer config param - typeahead-standalone.js" class="section-link">tokenizer</a></li>
               <li><a href="#config?id=scrolloptions" title="listScrollOptions config param - typeahead-standalone.js" class="section-link">listScrollOptions</a></li>
               <li><a href="#config?id=retainFocus" title="retainFocus config param - typeahead-standalone.js" class="section-link">retainFocus</a></li>
+              <li><a href="#config?id=hooks" title="Hooks config param - typeahead-standalone.js" class="section-link">hooks</a></li>
               <li><a href="#config?id=templates" title="templates config param - typeahead-standalone.js" class="section-link">templates</a></li>
             </ol>
           </li>
@@ -191,6 +192,7 @@ <h5 class="center">
                   <li><a href="#config?id=tokenizer" title="tokenizer config param - typeahead-standalone.js" class="section-link">tokenizer</a></li>
                   <li><a href="#config?id=scrolloptions" title="tokenizer config param - typeahead-standalone.js" class="section-link">listScrollOptions</a></li>
                   <li><a href="#config?id=retainFocus" title="retainFocus config param - typeahead-standalone.js" class="section-link">retainFocus</a></li>
+                  <li><a href="#config?id=hooks" title="Hooks config param - typeahead-standalone.js" class="section-link">hooks</a></li>
                   <li><a href="#config?id=templates" title="templates config param - typeahead-standalone.js" class="section-link">templates</a></li>
                 </ol>
               </li>

docs/pages/config.html

@@ -934,6 +934,49 @@ <h4><a href="#config?id=retainFocus" id="retainFocus" title="retainFocus config
 });</pre>
 </div>
 
+<hr>
+
+<h4><a href="#config?id=hooks" id="hooks" title="Hooks config param - typeahead-standalone.js" class="submenu-link section-link">15. 🪝 hooks</h4></a>
+
+<p>
+  The <code>hooks</code> config option is useful to execute arbitrary code at specific moments in typeahead's lifecycle.
+  Currently, there is 1 hook available - <code>updateHits</code> which is am async function that receives 1 parameter <b>resultSet</b>
+  containing 3 properties:
+  <ul>
+    <li>- items (the suggestions returned by the search index)</li>
+    <li>- query (the users input query),</li>
+    <li>- count (the total number of suggestions found in the search index).</li>
+  </ul>
+  This hook is executed before the suggestions are displayed to the user and allows you to override the results returned by
+  the search index in any way that you'd like. You can add, remove, modify, filter, sort suggestions and being an async function,
+  you can also make AJAX requests to fetch new results if needed.
+</p>
+<div class="codeContainer">
+  <span class="lang">JS</span>
+  <span class="copy" title="Copy to Clipboard"><i class="far fa-copy"></i></span>
+  <pre class="hljs language-js">
+typeahead({
+  input: document.querySelector(".myInput"),
+  source: {
+    // ...
+  },
+  hooks: {
+    updateHits: (resultSet) => {
+      resultSet.items.push({name: "new suggestion"}); // add new suggestion
+      // resultSet.items.filter( ... ); // filter the suggestions
+      // resultSet.items.sort( ... );  // custom sort the suggestions
+
+      // you can also make an AJAX request to fetch results
+      // const response = await fetch('https://example.com', { method: 'GET'});
+      // const text = await response.text();
+      // resultSet.items = text && JSON.parse(text);
+
+      return resultSet; // you must return the resultSet
+    },
+  }
+});</pre>
+</div>
+
 <hr>
 <h4><a href="#config?id=templates" id="templates" title="templates config param - typeahead-standalone.js" class="submenu-link section-link">16. 🎨 templates</h4></a>