♻️ chore: minor refactoring of retainFocus option and its docs

README.md

@@ -127,7 +127,7 @@ You can pass the following config options to `typeahead-standalone`:
 |`display(selectedItem, event?) => string`|This callback is executed when the user selects an item from the suggestions. The current suggestion/item is passed as a parameter and it **must return a string** which is set as the input's value. The 2nd *optional* parameter `event` is a Mouse/Keyboard event which can be used to track user interaction or for analytics. It defaults to `null`. |Returns the string representation of the selected item|
 |`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`| Prevents the default tab key behavior when the list of suggestions is open. Disable this if you want to allow the default tab action to occur, for example, if you want to apply the suggestion and immediately move the focus to the next element on the page afterwards without having to press the tab key again. | `true`|
+|`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`|
 
 ---
 

docs/pages/config.html

@@ -885,7 +885,7 @@ <h4><a href="#config?id=tokenizer" id="tokenizer" title="tokenizer config param
 </p>
 
 <hr>
-<h4><a href="#config?id=scrolloptions" id="scrolloptions" title="listScrollOptions config param - typeahead-standalone.js" class="submenu-link section-link">14. 🪙 listScrollOptions</h4></a>
+<h4><a href="#config?id=scrolloptions" id="scrolloptions" title="listScrollOptions config param - typeahead-standalone.js" class="submenu-link section-link">14. 📜 listScrollOptions</h4></a>
 
 <p>
  The <code>listScrollOptions</code> config option is used to have fine control over the scroll behaviour for a large list of suggestions that needs scrolling.
@@ -913,17 +913,29 @@ <h4><a href="#config?id=scrolloptions" id="scrolloptions" title="listScrollOptio
 </p>
 
 <hr>
-<h4><a href="#config?id=retainFocus" id="retainFocus" title="retainFocus config param - typeahead-standalone.js" class="submenu-link section-link">15. 🪙 retainFocus</h4></a>
+<h4><a href="#config?id=retainFocus" id="retainFocus" title="retainFocus config param - typeahead-standalone.js" class="submenu-link section-link">15. 🎯 retainFocus</h4></a>
 
 <p>
- The <code>retainFocus</code> config option is used to prevent the default action of the <kbd>Tab</kbd> key when the list of suggestions is open.
- By default, when the list of suggestions is open, pressing the <kbd>Tab</kbd> key will select the first suggestion and stay in the input field. By pressing the <kbd>Tab</kbd> key again, the focus will move to the next element on the page.
+ The <code>retainFocus</code> config option is useful to control the focus on pressing the <kbd>Tab</kbd> key when the list of suggestions is open.
+ When enabled (this is the default behaviour), pressing the <kbd>Tab</kbd> key will select the first suggestion & the focus will return to the input field.
+ By pressing the <kbd>Tab</kbd> key again, the focus will move to the next element on the page.
  When this option is set to <code>false</code>, pressing the <kbd>Tab</kbd> key will select the first suggestion and immediately move the focus to the next element on the page.
- This option is set to <code>true</code> by default.
 </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: {
+ // ...
+ },
+ retainFocus: false, // default -> true
+});</pre>
+</div>
 
 <hr>
-<h4><a href="#config?id=templates" id="templates" title="templates config param - typeahead-standalone.js" class="submenu-link section-link">15. 🎨 templates</h4></a>
+<h4><a href="#config?id=templates" id="templates" title="templates config param - typeahead-standalone.js" class="submenu-link section-link">16. 🎨 templates</h4></a>
 
 <p>
  The <code>templates</code> config option is used to customize the

src/typeahead-standalone.ts

@@ -68,7 +68,6 @@ const typeahead = <T extends Dictionary>(config: typeaheadConfig<T>): typeaheadR
  ...(config.classNames || {}),
  };
  const listScrollOptions: ScrollIntoViewOptions = { block: 'nearest', ...(config.listScrollOptions || {}) };
- const retainFocus = config.retainFocus === false ? false : true;
 
  // validate presence of atleast one data-source
  if (!local && !prefetch && !remote) throw new Error('e02');
@@ -488,9 +487,7 @@ const typeahead = <T extends Dictionary>(config: typeaheadConfig<T>): typeaheadR
  }
 
  if (ev.key === 'Tab' && isListOpen()) {
- if (retainFocus) {
- ev.preventDefault();
- }
+ config.retainFocus !== false && ev.preventDefault();
  useSelectedValue(true);
  }
  };