npm package: @sti-uff/autocomplete
Description: Wrapper para @tarekraafat/autocomplete.js
Author: Leonardo Gurgel
Latest version: 1.0.0

# Sti Autocomplete

Wrapper para ![@tarekraafat/autocomplete.js](https://tarekraafat.github.io/autoComplete.js/) com padrões sanos  
A intenção deste projeto é tornar mais fácil a utilização da biblioteca citada acima,  
diminuindo a quantidade de opções e permitindo alteração de padrões globais.  

## Instalação

```bash
  npm i @sti-uff/autocomplete
```

ou  

```bash
  yarn add @sti-uff/autocomplete
```

## Exemplos de Uso Básico

O autocomplete pode ser usado de diversas formas.  
Dentre elas, temos os seguintes exemplos:  

### Busca em Client Side

```erb
  <%= f.text_field :id_orgaopai, placeholder: f.object.orgaopai.desc_orgao %>
```

```typescript
  import autoComplete from '@sti-uff/autocomplete'

  autoComplete({
    input: '#orgao_id_orgaopai',
    cache: true, // a função src será chamada somente uma vez
    searchKeys: ['desc_orgao', 'sigla'], // a primeira chave preencherá o placeholder ao selecionar um valor
    valueKey: 'id_orgao', // o valor desta chave será enviado ao servidor pelo formulário
    src: async() => {
      const response = await fetch('/api/orgaos')
      return response.json()
    }
  })
```

### Busca em Server Side

```html
  <input type="text" id="autocomplete-alunos">
```

```typescript
  import autoComplete from '@sti-uff/autocomplete'

  interface Aluno {
    id: number
    nome: string
    matricula: string
    iduff: string
    idCurso: number
  }

  autoComplete({
    input: '#autocomplete-alunos',
    cache: false, // a função src será chamada em toda busca
    searchKeys: ['nome', 'matricula', 'iduff'], // a primeira chave preencherá o placeholder ao selecionar um valor
    valueKey: 'id', // o valor desta chave será enviado ao servidor pelo formulário
    src: async query => {
      const response = await fetch(`/api/alunos?q=${query}`) // passamos a query adiante ao server
      return response.json() as Aluno[]
    }
  })
```

## Carregando um autoComplete que já possua um valor preenchido

Para trazer um autoComplete já preenchido, garanta que:

- O `value` do input esteja preenchido com o atributo definido em `valueKey`
- O `placeholder` do input esteja preenchido com o primeiro atributo definido em `searchKeys`

## Estilização

Segue um html simplificado mostrando a estrutura do autocomplete:

```html
<div class="autoComplete_wrapper">
  <input type="search">
  <ul class="autoComplete_results">
    <span>
      <p>Mostrando <strong>15</strong> de <strong>5360</strong> resultados</p>
      <button type="button" class="autoComplete_clear">Limpar Seleção</button>
    </span>
    <li role="option"><mark>Leonar</mark>do Gurgel</li>
    {...}
  </ul>
</div>
<input type="hidden">
```

## Uso com tipagem

Essa bilioteca é completamente tipada para facilitar a utilização.  
Portanto, é possível utilizá-la com TypeScript.
Diversas interfaces estão disponíveis para importação

```typescript
  import autoComplete, { AutoCompleteEvent } from '@sti-uff/autocomplete'

  interface Aluno {
    id: number
    nome: string
    matricula: string
    iduff: string
    idCurso: number
  }

  const input = document.getElementById('autocomplete-alunos') as HTMLInputElement

  autoComplete<Aluno>({
    input,
    cache: false,
    valueKey: 'id',
    searchKeys: ['nome', 'matricula', 'iduff'],
    src: async query => {
      const response = await fetch(`/api/alunos?q=${query}`)
      return response.json()
    }
  })

  input.addEventListener('select', (event: AutoCompleteEvent<Aluno>) => {
    console.log('nome do aluno: ', event.detail.selection.value.nome)
    atualizaLista()
  })

  function atualizaLista() {
    // ...
  }
```

## Api Reference

Para todos as anotações abaixo, **T** é o tipo dos objetos retornados

### export interface ![AutoCompleteOptions&lt;T&gt;](./docs/interfaces/AutoCompleteOptions.md)

### export interface ![AutoCompleteResult&lt;T&gt;](./docs/interfaces/AutoCompleteResult.md)

### export class ![AutoComplete&lt;T&gt;](https://tarekraafat.github.io/autoComplete.js/#/usage)