<commit_before>jQuery#typeahead
----------------

The UI component of typeahead.js is a available as a jQuery plugin. It's 
responsible for rendering suggestions and handling DOM interactions.

Table of Contents
-----------------

* [Features](#features)
* [Usage](#usage)
  * [API](#api)
  * [Options](#options)
  * [Datasets](#datasets)
  * [Custom Events](#custom-events)
  * [Look and Feel](#look-and-feel)
* [Bloodhound Integration](#bloodhound-integration)

Features
--------

* Displays suggestions to end-users as they type
* Shows top suggestion as a hint (i.e. background text)
* Supports custom templates to allow for UI flexibility
* Works well with RTL languages and input method editors
* Highlights query matches within the suggestion
* Triggers custom events

Usage
-----

### API

#### jQuery#typeahead(options, [\*datasets])

Turns any `input[type="text"]` element into a typeahead. `options` is an 
options hash that's used to configure the typeahead to your liking. Refer to 
[Options](#options) for more info regarding the available configs. Subsequent 
arguments (`*datasets`), are individual option hashes for datasets. For more 
details regarding datasets, refer to [Datasets](#datasets).

```javascript
$('.typeahead').typeahead({
  minLength: 3,
  highlight: true,
},
{
  name: 'my-dataset',
  source: mySource
});
```

#### jQuery#typeahead('destroy')
<commit_msg>Add UI specification to plugin doc.<commit_after>jQuery#typeahead
----------------

The UI component of typeahead.js is a available as a jQuery plugin. It's 
responsible for rendering suggestions and handling DOM interactions.

Table of Contents
-----------------

* [Features](#features)
* [Specification](#specification)
* [Usage](#usage)
  * [API](#api)
  * [Options](#options)
  * [Datasets](#datasets)
  * [Custom Events](#custom-events)
  * [Look and Feel](#look-and-feel)
* [Bloodhound Integration](#bloodhound-integration)

Features
--------

* Displays suggestions to end-users as they type
* Shows top suggestion as a hint (i.e. background text)
* Supports custom templates to allow for UI flexibility
* Works well with RTL languages and input method editors
* Highlights query matches within the suggestion
* Triggers custom events

Specification
-------------

In an effort to take advantage of the pre-existing knowledge of typeahead.js 
users, the behavior of the typeahead.js UI is modeled after google.com's search 
box. Below details how the UI reacts to pertinent events.

### Input Control Gains Focus

The typeahead is activated and begins listening for keyboard events.

### Input Control Loses Focus

The typeahead is deactivated and the dropdown menu is cleared and closed.

### Value of the Input Control Changes

When the value of the input control changes, the following happens:

* If the dropdown menu was closed, it opens.
* Suggestions are rendered.
* If the new query is a prefix of the top suggestion, the hint is updated. 
  Otherwise the hint is cleared.
* Language direction detection is performed and the proper CSS styles are 
  applied.

### Up Arrow is Keyed

The result of keying the up arrow is dependent on the state of the typeahead.

If the dropdown menu is closed, keying the up arrow key will open the dropdown 
menu and render suggestions.

If the dropdown menu is open and contains suggestions, keying the up arrow 
key will move the typeahead cursor down one suggestion.

If the dropdown menu is open and contains no suggestions, keying the up arrow 
key will result in no visible changes.

### Down Arrow is Keyed

### Left Arrow is Keyed

Ignored by typeahead.js.

**Note**: this assumes the language is LTR; for RTL languages, the behavior for 
keying the left and right arrow keys are swapped.

### Right Arrow is Keyed

If a hint is showing and the text cursor is at the end of the query, the query
is updated to the value of the hint.

**Note**: this assumes the language is LTR; for RTL languages, the behavior for 
keying the left and right arrow keys are swapped.

### Tab is Keyed

The result of keying the tab key is dependent on the state of the typeahead.

If the dropdown menu is opened and the cursor is over a suggestion, keying the 
tab key will select that suggestion.

If a hint is showing, the query is updated to the value of the hint.

### Enter is Keyed

If the dropdown menu cursor is over a suggestion, keying the enter key will 
select that suggestion.

### Esc is Keyed

Closes the dropdown menu.

Usage
-----

### API

#### jQuery#typeahead(options, [\*datasets])

Turns any `input[type="text"]` element into a typeahead. `options` is an 
options hash that's used to configure the typeahead to your liking. Refer to 
[Options](#options) for more info regarding the available configs. Subsequent 
arguments (`*datasets`), are individual option hashes for datasets. For more 
details regarding datasets, refer to [Datasets](#datasets).

```javascript
$('.typeahead').typeahead({
  minLength: 3,
  highlight: true,
},
{
  name: 'my-dataset',
  source: mySource
});
```

#### jQuery#typeahead('destroy')

{'fraction_non_alphanumeric': 0.10181531176006314, 'fraction_numerical': 0.0003946329913180742, 'mean_word_length': 3.9990138067061145, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2936679', 'n_tokens_mistral': 1444, 'n_tokens_neox': 1349, 'n_words': 664}