# Chips

![Status](https://img.shields.io/badge/status-stable-brightgreen)

Componente para entrada de múltiplos valores em formato de chips/tags removíveis. Permite adicionar e remover itens de texto livremente, com suporte a limite de itens, prevenção de duplicatas, filtro de teclas e template personalizado. Implementa `ControlValueAccessor` para uso em formulários Angular.

## Quando usar

- Tags ou palavras-chave editáveis em formulários
- Campo de destinatários de e-mail com múltiplos endereços
- Filtros de busca onde o usuário adiciona múltiplos termos
- Listas de valores editáveis onde cada item pode ser removido individualmente

## Quando não usar

- Para exibir chips não editáveis (somente leitura) — use `Badge` ou `TokenList`
- Para seleção de opções de uma lista predefinida com busca — use `Autocomplete` com `multiple: true`
- Quando apenas um valor é esperado — use `Input` simples

## Instalação

```typescript
import { ChipsModule } from '@seniorsistemas/angular-components/chips';

@NgModule({
  imports: [ChipsModule],
})
export class MeuModule {}
```

## Uso básico

```html
<s-chips placeholder="Adicionar tag..." [(value)]="tags" />
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `value` | `string[] \| any[]` | `[]` | não | Lista de chips exibidos |
| `placeholder` | `string` | `undefined` | não | Texto de placeholder do campo |
| `field` | `string` | `''` | não | Chave do objeto para exibição quando `value` é array de objetos |
| `disabled` | `boolean` | `false` | não | Desabilita adição e remoção de chips |
| `max` | `number` | `Infinity` | não | Número máximo de chips permitidos |
| `maxLength` | `number` | `Infinity` | não | Comprimento máximo do texto de cada chip |
| `allowDuplicated` | `boolean` | `true` | não | Permite chips com valor duplicado |
| `caseSensitiveDuplication` | `boolean` | `false` | não | Distingue maiúsculas na verificação de duplicatas |
| `addOnTab` | `boolean` | `true` | não | Adiciona chip ao pressionar Tab |
| `addOnBlur` | `boolean` | `true` | não | Adiciona chip ao perder o foco |
| `separator` | `string` | `''` | não | Caractere que confirma adição de chip ao ser digitado |
| `autofocus` | `boolean` | `false` | não | Foca automaticamente o campo ao renderizar |
| `infoLabel` | `string` | `''` | não | Texto informativo exibido abaixo do campo |
| `keyFilter` | `RegExp \| KeyFilterPattern` | `undefined` | não | Filtro de teclas para restringir caracteres aceitos |
| `showTooltip` | `boolean` | `true` | não | Exibe tooltip em chips com texto truncado |
| `maxLengthRenderWithoutTooltip` | `number` | `20` | não | Caracteres exibidos antes de truncar o chip |
| `inputId` | `string` | `chips-{hash}` | não | ID do `<input>` interno |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `added` | `EventEmitter<ChipAddEvent>` | Emitido quando um chip é adicionado |
| `removed` | `EventEmitter<ChipRemoveEvent>` | Emitido quando um chip é removido |
| `chipClicked` | `EventEmitter<ChipClickEvent>` | Emitido ao clicar em um chip |
| `focused` | `EventEmitter<FocusEvent>` | Emitido quando o campo recebe foco |
| `focusLost` | `EventEmitter<FocusEvent>` | Emitido quando o campo perde foco |
| `valueChange` | `EventEmitter<string[] \| any[]>` | Emitido quando a lista de chips é alterada |

### Tipos

```typescript
type ChipAddEvent = { value: any };
type ChipRemoveEvent = { originalEvent: Event; value: any };
type ChipClickEvent = { originalEvent: Event; value: any };
```

## Exemplos

### Tags básicas

```html
<s-chips
  placeholder="Adicione países..."
  [value]="['Brasil', 'Argentina', 'Chile']">
</s-chips>
```

### Sem duplicatas, com separador por vírgula

```html
<s-chips
  placeholder="Digite emails separados por vírgula..."
  [value]="emails"
  [allowDuplicated]="false"
  separator=","
  infoLabel="Adicione múltiplos emails separados por vírgula">
</s-chips>
```

### Com limite de itens

```html
<s-chips
  placeholder="Máximo 5 tags..."
  [value]="tags"
  [max]="5"
  infoLabel="Você pode adicionar até 5 tags">
</s-chips>
```

### Com objetos complexos

```html
<s-chips
  placeholder="Adicione países..."
  [value]="paises"
  field="nome">
</s-chips>
```

```typescript
paises = [
  { id: 1, nome: 'Brasil', codigo: 'BR' },
  { id: 2, nome: 'Argentina', codigo: 'AR' },
];
```

### Reagindo a eventos

```html
<s-chips
  [value]="tags"
  (added)="onAdicionado($event)"
  (removed)="onRemovido($event)"
  (chipClicked)="onCliqueChip($event)">
</s-chips>
```

## Acessibilidade

- O campo de entrada é um `<input>` acessível via teclado
- **Enter** confirma adição do chip; **Tab** também pode confirmar (configurável)
- Os botões de remoção de cada chip são acessíveis via teclado
- Use `aria-label` ou `<label for="...">` apontando para `inputId` para associar um rótulo ao campo

## Componentes relacionados

- [`Autocomplete`](../autocomplete/README.md) com `multiple: true` — quando os chips devem ser selecionados de uma lista predefinida com busca
- [`Badge`](../badge/README.md) — para exibir chips não editáveis (somente leitura)