Textcomplete

https://github.com/yuku/textcomplete
Admin
Textcomplete is a library providing autocomplete functionality for HTMLTextAreaElement and other...
Tokens:9,798
Snippets:143
Trust Score:9.7
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and View Documentation

Source: https://github.com/yuku/textcomplete/blob/main/README.md

Run these commands to install project dependencies and start the documentation server. The documentation will be available at http://localhost:1234.

```bash
yarn install
yarn docs
```

--------------------------------

### Install @textcomplete/textarea

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/README.md

Install the core and textarea packages using npm.

```bash
npm install --save @textcomplete/core @textcomplete/textarea
```

--------------------------------

### Install Textcomplete Core and Contenteditable

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-contenteditable/README.md

Install the necessary packages for Textcomplete core and the contenteditable editor.

```bash
npm install --save @textcomplete/core @textcomplete/contenteditable
```

--------------------------------

### Start Development Server

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/development.md

Starts the local development server for viewing documentation. Access the documentation at http://localhost:8080/.

```shell
npm start
# or
yarn start
```

--------------------------------

### Install Dependencies

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/development.md

Installs project dependencies using npm or yarn.

```shell
npm install
# or
yarn install
```

--------------------------------

### Install Dependencies for CodeMirror

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-codemirror/README.md

Install the necessary packages for Textcomplete core, CodeMirror integration, and CodeMirror itself.

```bash
npm install --save @textcomplete/core @textcomplete/codemirror codemirror
```

--------------------------------

### Configuring Textcomplete with Strategies

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

An example of initializing textcomplete on a textarea with two strategies: mention and emoji. It also demonstrates setting global options like `maxCount` and `debounce`.

```javascript
$('textarea').textcomplete([
  {
    match: /(^|\s)@(\w*)$/,
    search: function (term, callback) {
      callback(cache[term], true);
      $.getJSON('/search', { q: term })
        .done(function (resp) { callback(resp); })
        .fail(function ()     { callback([]);   });
    },
    replace: function (value) {
      return '$1@' + value + ' ';
    },
    cache: true
  },
  {
    match: /(^|\s):(\w*)$/,
    search: function (term, callback) {
      var regexp = new RegExp('^' + term);
      callback($.grep(emojies, function (emoji) {
        return regexp.test(emoji);
      }));
    },
    replace: function (value) {
      return '$1:' + value + ': ';
    }
  }
], { maxCount: 20, debounce: 500 });

```

--------------------------------

### Install Textcomplete via NPM

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/getting-started.md

Install the textcomplete package using npm for Node.js projects.

```bash
npm install textcomplete
```

--------------------------------

### Setting Dropdown Placement

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Demonstrates how to set the placement of the dropdown menu using the `placementStr` option. This example shows positioning the dropdown at the top and absolute left.

```javascript
var placementStr = 'top|absleft';

```

--------------------------------

### Custom Keyboard Shortcut Handling

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Provides an example of how to implement custom keyboard shortcuts for textcomplete using the `onKeydown` option. This allows for custom command execution based on key presses.

```javascript
var onKeydownFunc = function (e, commands) {
  // `commands` has `KEY_UP`, `KEY_DOWN`, `KEY_ENTER`, `KEY_PAGEUP`, `KEY_PAGEDOWN`,
  // `KEY_ESCAPE` and `SKIP_DEFAULT`.
  if (e.ctrlKey && e.keyCode === 74) {
    // Treat CTRL-J as enter key.
    return commands.KEY_ENTER;
  }
  // If the function does not return a result or undefined is returned,
  // the plugin uses default behavior.
};

```

--------------------------------

### Sample CSS for Custom Styling

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/style.md

This CSS can be used as a starting point for custom styling the dropdown menu if Bootstrap is not being used. It defines borders, background colors, padding, and hover/active states.

```css
.textcomplete-dropdown {
    border: 1px solid #ddd;
    background-color: white;
}

.textcomplete-dropdown li {
    border-top: 1px solid #ddd;
    padding: 2px 5px;
}

.textcomplete-dropdown li:first-child {
    border-top: none;
}

.textcomplete-dropdown li:hover,
.textcomplete-dropdown .active {
    background-color: rgb(110, 183, 219);
}

.textcomplete-dropdown {
    list-style: none;
    padding: 0;
    margin: 0;
}

.textcomplete-dropdown a:hover {
    cursor: pointer;
}
```

--------------------------------

### Match Regular Expression Example

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Defines a regular expression to capture terms starting with '@'. The 'indexNumber' specifies which capturing group to use as the search term.

```javascript
// Detect the word starting with '@' as a query term.
var matchRegExpOrFunc = /(^|\s)@(\w*)$/;
var indexNumber = 2;
// Normalizing the input text.
var contextFunc = function (text) { return text.toLowerCase(); };
```

--------------------------------

### Release a New Version

Source: https://github.com/yuku/textcomplete/blob/main/README.md

Execute this command to initiate the release process for a new version of the project. A tag will be shown for creating the release.

```bash
yarn release
```

--------------------------------

### Initialize Textcomplete with CodeMirror

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-codemirror/README.md

Set up Textcomplete for a CodeMirror instance by importing required modules and initializing the editor and Textcomplete.

```javascript
const { Textcomplete } = require("@textcomplete/core")
const { CodeMirrorEditor } = require("@textcomplete/codemirror")

const CodeMirror = require("codemirror")

const cm = CodeMirror(myElement)
const editor = new CodeMirrorEditor(cm)
const textcomplete = new Textcomplete(editor, strategies, option)
```

--------------------------------

### Initialize Textcomplete

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/getting-started.md

Initialize Textcomplete with an editor instance and optional configuration options.

```javascript
var textcomplete = new Textcomplete(editor, {
  dropdown: {
    maxCount: Infinity
  }
})
```

--------------------------------

### Initialize Textcomplete with TextareaEditor

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/README.md

Import and initialize Textcomplete with TextareaEditor, strategies, and options.

```javascript
const { Textcomplete } = require("@textcomplete/core")
const { TextareaEditor } = require("@textcomplete/textarea")

const editor = new TextareaEditor(textareaElement)
const textcomplete = new Textcomplete(editor, strategies, option)
```

--------------------------------

### Run Tests

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/development.md

Executes the project's test suite using npm or yarn.

```shell
npm test
# or
yarn test
```

--------------------------------

### Initialize Textarea Editor

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/getting-started.md

Create a Textarea editor instance by referencing a textarea HTML element.

```javascript
var textareaElement = document.getElementById('your-textarea-element')
var editor = new Textarea(textareaElement);
```

--------------------------------

### Basic Autocomplete Initialization

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/README.md

Initializes textcomplete on a textarea element with a basic word matching and replacement strategy. Requires jQuery or Zepto.

```javascript
$"textarea").textcomplete([{
    match: /(^|\b)(\w{2,})$/,
    search: function (term, callback) {
        var words = ['google', 'facebook', 'github', 'microsoft', 'yahoo'];
        callback($.map(words, function (word) {
            return word.indexOf(term) === 0 ? word : null;
        }));
    },
    replace: function (word) {
        return word + ' ';
    }
}]);
```

--------------------------------

### DropdownOptions

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Configuration options for the dropdown view.

```APIDOC
## DropdownOptions

Type: {className: [string]?, footer: function (any): ([string] | [string])?, header: function (any): ([string] | [string])?, maxCount: [number]?, placement: [string]?, rotate: [boolean]?, style: {}?, item: [DropdownItemOptions](#dropdownitemoptions)?, parent: [HTMLElement]?}

**Properties**

- `className` **[string]?**
- `footer` **function (any): ([string] | [string])?**
- `header` **function (any): ([string] | [string])?**
- `maxCount` **[number]?**
- `placement` **[string]?**
- `rotate` **[boolean]?**
- `style` **{}?**
- `item` **[DropdownItemOptions](#dropdownitemoptions)?**
- `parent` **[HTMLElement]?**
```

--------------------------------

### Query.build

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Builds a Query object from the given string if it matches the string. It requires the strategy and the text preceding the cursor.

```APIDOC
## Query.build

### Description
Build a Query object by the given string if this matches to the string.

### Parameters
- `strategy` **[Strategy](#strategy)**
- `text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Head to input cursor.

### Returns
**[Query](#query)?**
```

--------------------------------

### Initialize Textcomplete with Contenteditable Editor

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-contenteditable/README.md

Initialize Textcomplete by creating a ContenteditableEditor instance and passing it to the Textcomplete constructor along with strategies and options.

```javascript
const { Textcomplete } = require("@textcomplete/core")
const { ContenteditableEditor } = require("@textcomplete/contenteditable")

const editor = new ContenteditableEditor(myContenteditableElement)
const textcomplete = new Textcomplete(editor, strategies, option)
```

--------------------------------

### Combine Local and Remote Data

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Integrate both local and remote data sources for autocompletion by invoking the callback function appropriately for each data type.

```javascript
search: function (term, callback) {
  callback(cache[term], true);
  $.getJSON('/search', { q: term })
    .done(function (resp) { callback(resp); })
    .fail(function ()     { callback([]);   });
}
```

--------------------------------

### Registering a New Strategy

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Use this snippet to register a new autocompletion strategy with Textcomplete. It requires defining a match pattern, a search function to fetch suggestions, and a replace function to insert the selected suggestion.

```javascript
textcomplete.register([
  {
    match: /(^|\s)(\w+)$/,
    search: function (term, callback) {
      $.ajax({
        ... 
      })
      .done(callback)
      .fail([]);
    },
    replace: function (value) {
      return '$1' + value + ' ';
    }
  }
]);
```

--------------------------------

### Query.execute

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Invokes the search strategy and calls back the provided function with an array of SearchResult objects.

```APIDOC
## Query.execute

### Description
Invoke search strategy and callback the given function.

### Parameters
- `callback` **function ([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[SearchResult](#searchresult)>): void**
```

--------------------------------

### TextcompleteOptions

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Defines the options for configuring the Textcomplete instance, primarily related to dropdown behavior.

```APIDOC
## TextcompleteOptions

Type: {dropdown: [DropdownOptions](#dropdownoptions)?}

**Properties**

- `dropdown` **[DropdownOptions](#dropdownoptions)?**
```

--------------------------------

### Textcomplete Options Object

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Defines the available options for configuring textcomplete, such as adapter, appendTo, height, and more. These options control the behavior and appearance of the dropdown.

```javascript
var option = {
  adapter:           adapterClass,
  appendTo:          appendToString,
  className:         classNameStr,
  debounce:          debounceNumber,
  dropdownClassName: dropdownClassNameStr,
  footer:            footerStrOrFunc,
  header:            headerStrOrFunc,
  height:            heightNumber,
  maxCount:          maxCountNumber,
  noResultsMessage:  noResultsMessageStrOrFunc,
  onKeydown:         onKeydownFunc,
  placement:         placementStr,
  rightEdgeOffset:   rightEdgeOffsetInteger,
  zIndex:            zIndexStr,
};

```

--------------------------------

### Strategy Object Properties

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

A strategy object requires 'match', 'search', and 'replace' properties. Optional properties like 'index', 'template', 'cache', 'context', and 'idProperty' allow for customization.

```javascript
var strategy = {
  // Required
  match:      matchRegExpOrFunc,
  search:     searchFunc,
  replace:    replaceFunc,

  // Optional                 // Default
  cache:      cacheBoolean,   // false
  context:    contextFunc,    // function (text) { return true; }
  id:         idString,       // null
  idProperty: idPropertyStr,  // null
  index:      indexNumber,    // 2
  template:   templateFunc,   // function (value) { return value; }
}
```

--------------------------------

### getBeforeCursor

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Returns the editor's string value from the beginning up to the cursor's position. Returns null if the selection is a range instead of a cursor.

```APIDOC
## getBeforeCursor

### Description
Editor string value from head to cursor. Returns null if selection type is range not cursor.

### Returns
**[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**
```

--------------------------------

### Textcomplete

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

The core mediator of the textcomplete library, extending EventEmitter and managing editor instances and strategies.

```APIDOC
## Textcomplete

**Extends EventEmitter**

The core of textcomplete. It acts as a mediator.

**Parameters**

- `editor` **[Editor](#editor)**
- `options` **[TextcompleteOptions](#textcompleteoptions)**  (optional, default `{}`)

### destroy

**Parameters**

- `destroyEditor` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)**  (optional, default `true`)

Returns **this**

### hide

Returns **this**

### register

**Parameters**

- `strategyPropsArray` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[StrategyProperties](#strategyproperties)>**

**Examples**

```javascript
textcomplete.register([
  {
    match: /(^|\s)(\w+)$/,
    search: function (term, callback) {
      $.ajax({ ... })
        .done(callback)
        .fail([]);
    },
    replace: function (value) {
      return '$1' + value + ' ';
    }
  }
]);
```

Returns **this**

### trigger

Start autocompleting.

**Parameters**

- `text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Head to input cursor.

Returns **this**
```

--------------------------------

### Strategy

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Represents a single strategy within textcomplete, encapsulating its properties and methods.

```APIDOC
## Strategy

Encapsulate a single strategy.

**Parameters**

- `props` **[StrategyProperties](#strategyproperties)**

### destroy

Returns **this**

### replace

**Parameters**

- `data` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** An element of array callbacked by search function.
```

--------------------------------

### Search Function with Local Cache and API Call

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Implements a search function that first checks a local cache and then makes an API call for results. It uses a callback to provide results, supporting immediate display of cached data.

```javascript
var searchFunc = function (term, callback, match) {
  // term === match[indexNumber]
  callback(cache[term], true); // Show local cache immediately.

  $.getJSON('/search', { q: term })
    .done(function (resp) {
      callback(resp); // `resp` must be an Array
    })
    .fail(function () {
      callback([]); // Callback must be invoked even if something went wrong.
    });
};
```

--------------------------------

### StrategyProperties

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Defines the properties for a textcomplete strategy, including matching, searching, replacing, and caching mechanisms.

```APIDOC
## StrategyProperties

Properties for a strategy.

- `match` **([RegExp](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp) | function ([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)): (MatchData | null))
- `search` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)**
- `replace` **function (any): ([Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)> | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | null)**
- `cache` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?**
- `context` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?**
- `template` **function (any): [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**
- `index` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?**
- `id` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**
```

--------------------------------

### Require Textcomplete as CommonJS Module

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/getting-started.md

Import Textcomplete and Textarea modules in a CommonJS environment.

```javascript
var Textcomplete = require('textcomplete');
var Textarea = require('textcomplete/lib/textarea');
```

--------------------------------

### Include jQuery and Textcomplete

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Ensure jQuery is loaded before the Textcomplete plugin. This is a prerequisite for using the plugin.

```html
<script src="path/to/jquery.js"></script>
<script src="path/to/jquery.textcomplete.js"></script>
```

--------------------------------

### Dropdown

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Encapsulates a dropdown view, managing its display and interaction.

```APIDOC
## Dropdown

**Extends EventEmitter**

Encapsulate a dropdown view.

**Parameters**

- `options` **[DropdownOptions](#dropdownoptions)** 

**Properties**

- `shown` **[boolean]** Whether the #el is shown or not.
- `items` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[DropdownItem](#dropdownitem)>** The array of rendered dropdown items.

### destroy

Returns **this** 

### render

Render the given data as dropdown items.

**Parameters**

- `searchResults` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[SearchResult](#searchresult)>** 
- `cursorOffset` **[CursorOffset](#cursoroffset)** 

Returns **this** 

### deactivate

Hide the dropdown then sweep out items.

Returns **this** 

### select

**Parameters**

- `dropdownItem` **[DropdownItem](#dropdownitem)** 

Returns **this** 

### up

**Parameters**

- `e` **[CustomEvent](https://developer.mozilla.org/docs/Web/API/CustomEvent/CustomEvent)** 

Returns **this** 

### down

**Parameters**

- `e` **[CustomEvent](https://developer.mozilla.org/docs/Web/API/CustomEvent/CustomEvent)** 

Returns **this** 

### getActiveItem

Retrieve the active item.

Returns **([DropdownItem](#dropdownitem) | null)** 
```

--------------------------------

### getCode

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

A helper method for parsing KeyboardEvent. It takes a KeyboardEvent object and returns a KeyCode.

```APIDOC
## getCode

### Description
Helper method for parsing KeyboardEvent.

### Parameters
- `e` **[KeyboardEvent](https://developer.mozilla.org/docs/Web/API/KeyboardEvent)**

### Returns
**KeyCode**
```

--------------------------------

### Register Emoji Strategy

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/getting-started.md

Register a strategy for autocompleting emojis based on a pattern and search function.

```javascript
textcomplete.register([{
  // Emoji strategy
  match: /(^|\s):(\w+)$/,
  search: function (term, callback) {
    callback(emojies.filter(emoji => { return emoji.startsWith(term); }));
  },
  replace: function (value) {
    return '$1:' + value + ': ';
  }
}]);
```

--------------------------------

### Apply Strategies to Multiple Textareas

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Apply the same textcomplete strategies to multiple textarea elements by selecting them with a jQuery selector and initializing textcomplete.

```javascript
// All class="commentBody" elements share strategies.
$('.commentBody').textcomplete([ /* ... */ ]);
```

--------------------------------

### Handling textComplete Events

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/events.md

Listen for textComplete events like 'textComplete:select', 'textComplete:show', and 'textComplete:hide' on a textarea element to react to user interactions and dropdown state changes.

```javascript
$('#textarea')
    .textcomplete([/* ... */])
    .on({
        'textComplete:select': function (e, value, strategy) {
            alert(value);
        },
        'textComplete:show': function (e) {
            $(this).data('autocompleting', true);
        },
        'textComplete:hide': function (e) {
            $(this).data('autocompleting', false);
        }
    });
```

--------------------------------

### emitChangeEvent

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Emits a change event to trigger auto-completion. Child classes should call this method at the appropriate time.

```APIDOC
## emitChangeEvent

### Description
Emit a change event, which triggers auto completion. Child class must call this method at proper timing.

### Returns
**[CustomEvent](https://developer.mozilla.org/docs/Web/API/CustomEvent/CustomEvent)**
```

--------------------------------

### Textarea

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Encapsulates the target textarea element, extending the Editor class and providing methods for managing search results and cursor position.

```APIDOC
## Textarea

**Extends Editor**

Encapsulate the target textarea element.

**Parameters**

- `el` **[HTMLTextAreaElement](https://developer.mozilla.org/docs/Web/API/HTMLTextAreaElement)**

### destroy

Returns **this**

### applySearchResult

Implementation for [Editor#applySearchResult](#editorapplysearchresult)

**Parameters**

- `searchResult` **[SearchResult](#searchresult)**

### getCursorOffset

Implementation for [Editor#getCursorOffset](#editorgetcursoroffset)

### getBeforeCursor

Implementation for [Editor#getBeforeCursor](#editorgetbeforecursor)
```

--------------------------------

### Case-Insensitive Search with Callback

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Perform case-insensitive searches by converting the input term to lowercase within the search callback function and filtering the results.

```javascript
search: function (term, callback) {
    term = term.toLowerCase();
    callback($.map(words, function (word) {
        return word.toLowerCase().indexOf(term) === 0 ? word : null;
    }));
},
```

--------------------------------

### Case-Insensitive Search with Context

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Achieve case-insensitive searching by normalizing the input term to lowercase using the `context` option before the search is performed.

```javascript
context: function (text) { return text.toLowerCase(); },
```

--------------------------------

### Editor

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Abstract base class for editor implementations, defining the interface for textcomplete integration.

```APIDOC
## Editor

**Extends EventEmitter**

Abstract class representing a editor target.

Editor classes must implement `#applySearchResult`, `#getCursorOffset` and
`#getBeforeCursor` methods.

Editor classes must invoke `#emitMoveEvent`, `#emitEnterEvent`,
`#emitChangeEvent` and `#emitEscEvent` at proper timing.

### destroy

It is called when associated textcomplete object is destroyed.

Returns **this** 
```

--------------------------------

### Custom Template Function

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Provides a custom template function to format dropdown items, displaying the value in bold HTML tags. The default template simply returns the value.

```javascript
var templateFunc = function (value, term) {
  // `value` is an element of array callbacked by searchFunc.
  return '<b>' + value + '</b>';
};
// Default:
//   templateFunc = function (value) { return value; };
```

--------------------------------

### emitEnterEvent

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Emits an enter event to select the current search result. Child classes should call this method at the appropriate time.

```APIDOC
## emitEnterEvent

### Description
Emit a enter event, which selects current search result. Child class must call this method at proper timing.

### Returns
**[CustomEvent](https://developer.mozilla.org/docs/Web/API/CustomEvent/CustomEvent)**
```

--------------------------------

### CursorOffset

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Represents the cursor's position and dimensions within the editor.

```APIDOC
## CursorOffset

Type: {lineHeight: [number], top: [number], left: [number]?, right: [number]?, clientTop: [number]?}

**Properties**

- `lineHeight` **[number]** 
- `top` **[number]** 
- `left` **[number]?** 
- `right` **[number]?** 
- `clientTop` **[number]?** 
```

--------------------------------

### Include Textcomplete via Script Tag

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/getting-started.md

Include the bundled textcomplete.js script in your HTML for traditional web development.

```html
<script src="path/to/textcomplete/dist/textcomplete.js"></script>
<script>
  var Textarea = Textcomplete.editors.Textarea;
</script>
```

--------------------------------

### applySearchResult

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Called when a search result is selected by a user. It takes a SearchResult object as a parameter.

```APIDOC
## applySearchResult

### Description
It is called when a search result is selected by a user.

### Parameters
- `_` **[SearchResult](#searchresult)**

### Returns
**void**
```

--------------------------------

### Initialize Textcomplete on Textareas

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Apply Textcomplete to textarea elements using jQuery. It can also be applied to contenteditable or text input elements.

```javascript
$('textarea').textcomplete(strategies, option);  // Recommended.
// $('[contenteditable="true"]').textcomplete(strategies, option);
// $('input[type="text"]').textcomplete(strategies, option);
```

--------------------------------

### Define Strategies Array

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Strategies are defined as an array of objects, where each object represents a distinct autocompletion rule.

```javascript
var strategies = [
  // There are two strategies.
  strategy,
  { /* the other strategy */ }
];
```

--------------------------------

### Completer

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

The Completer class is the core engine for text completion. It manages strategies and runs the completion process.

```APIDOC
## Completer

**Extends EventEmitter**

Complete engine.

### destroy

Returns **this**

### registerStrategy

Register a strategy to the completer.

**Parameters**

- `strategy` **[Strategy](#strategy)** 

Returns **this** 

### run

**Parameters**

- `text` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Head to input cursor.

Returns **void** 
```

--------------------------------

### Replace Function for HTML Element Insertion with Cursor Repositioning

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Illustrates a replace function that returns an array of two strings. This allows for inserting HTML tags and precisely positioning the cursor between the opening and closing tags.

```javascript
var replaceFunc = function (value) {
  return ['$1<' + value + '>', '</' + value + '>'];
};
```

--------------------------------

### DropdownItem

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

The DropdownItem class encapsulates a single item within the dropdown list, providing methods for interaction and lifecycle management.

```APIDOC
## DropdownItem

Encapsulate an item of dropdown.

**Parameters**

- `searchResult` **[SearchResult](#searchresult)** 
- `options` **[DropdownItemOptions](#dropdownitemoptions)** 

### destroy

Try to free resources and perform other cleanup operations.

### appended

- **See: Dropdown#append**

Callbacked when it is appended to a dropdown.

**Parameters**

- `dropdown` **[Dropdown](#dropdown)** 

### activate

Deactivate active item then activate itself.

Returns **this** 

### next

Get the next sibling.

Returns **[DropdownItem](#dropdownitem)?** 

### prev

Get the previous sibling.

Returns **[DropdownItem](#dropdownitem)?** 
```

--------------------------------

### getCursorOffset

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Retrieves the absolute coordinates of the input cursor relative to the window's top-left corner.

```APIDOC
## getCursorOffset

### Description
The input cursor's absolute coordinates from the window's left top corner.

### Returns
**[CursorOffset](#cursoroffset)**
```

--------------------------------

### Change Trigger Token to '@'

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Customize the trigger token from the default ':' to '@' by defining the `match` and `replace` properties in your strategy.

```javascript
match: /(^|\s)@(\w*)$/,
replace: function (value) { return '$1@' + value + ' '; }
```

--------------------------------

### Trigger Textcomplete on Focus

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Show textcomplete when a textarea gains focus by calling the 'trigger' command within a `setTimeout` to ensure the cursor position is ready.

```javascript
$('textarea').on('focus', function () {
    var element = this;
    // Cursor has not set yet. And wait 100ms to skip global click event.
    setTimeout(function () {
        // Cursor is ready.
        $(element).textcomplete('trigger');
    }, 100);
});
```

--------------------------------

### Manually Trigger Textcomplete

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

Manually trigger the textcomplete search with a specific query or based on the current cursor position using the 'trigger' command.

```javascript
// Put manual search query.
$('textarea').textcomplete('trigger', 'query');

// Use current texts. It depends on the position of cursor.
$('textarea').textcomplete('trigger');
```

--------------------------------

### emitEscEvent

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Emits an esc event to hide the dropdown element. Child classes should call this method at the appropriate time.

```APIDOC
## emitEscEvent

### Description
Emit a esc event, which hides dropdown element. Child class must call this method at proper timing.

### Returns
**[CustomEvent](https://developer.mozilla.org/docs/Web/API/CustomEvent/CustomEvent)**
```

--------------------------------

### Destroying Textcomplete Instance

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Shows how to completely remove and destroy an active textcomplete instance from a textarea element.

```javascript
$('textarea').textcomplete('destroy');

```

--------------------------------

### HTML Structure of Dropdown Menu

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/style.md

This is the typical HTML structure generated by jquery-textcomplete for its dropdown menu. The content within the `<a>` tags is determined by the `templateFunc`.

```html
<ul class="dropdown-menu textcomplete-dropdown">
  <li class="textcomplete-item active" data-index="0"><a>...</a></li>
  <li class="textcomplete-item" data-index="1"><a>...</a></li>
  <li class="textcomplete-item" data-index="2"><a>...</a></li>
  <li class="textcomplete-item" data-index="3"><a>...</a></li>
  <li class="textcomplete-item" data-index="4"><a>...</a></li>
</ul>
```

--------------------------------

### emitMoveEvent

Source: https://github.com/yuku/textcomplete/blob/main/packages/textcomplete-textarea/doc/api.md

Emits a move event to adjust the active dropdown element. Child classes should call this method at the appropriate time with the correct parameter.

```APIDOC
## emitMoveEvent

### Description
Emit a move event, which moves active dropdown element. Child class must call this method at proper timing with proper parameter.

### Parameters
- `code` **(`"UP"` | `"DOWN"`)**

### Returns
**[CustomEvent](https://developer.mozilla.org/docs/Web/API/CustomEvent/CustomEvent)**
```

--------------------------------

### Replace Function for Simple Text Insertion

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/how_to_use.md

Defines a replace function that inserts the selected value into the textarea, followed by a space. This is used when an item is selected from the autocomplete dropdown.

```javascript
var replaceFunc = function (value, event) { return '$1@' + value + ' '; };
```

--------------------------------

### Remove Trigger Token After Selection

Source: https://github.com/yuku/textcomplete/blob/main/packages/jquery-textcomplete/doc/faq.md

If '@' is used solely as a trigger, modify the `match` and `replace` properties to remove it from the input after a user makes a selection.

```javascript
match: /(^|\s)(@\w*)$/
replace: function (value) { return '$1' + value + ' '; }
```
Tokens:
Raw