npm package: @ng-zi/extensions-chips
Description: Angular Material Extensions for chips
Latest version: 0.0.1

## MtxChips Component Overview

The `MtxChips` component provides a versatile and interactive way to display a list of items (chips) with various features, including autocomplete, avatars, drag-and-drop, and more.

## Features

| Feature                    | Description                                                                 |
|----------------------------|-----------------------------------------------------------------------------|
| **Basic Chips**            | Display a simple list of chips with customizable appearance.                |
| **Chips with Autocomplete**| Integrate autocomplete functionality for dynamic chip creation.             |
| **Chips with Avatar**      | Display avatars alongside chips for user or item representation.             |
| **Chips with Drag and Drop**| Enable reordering of chips through drag-and-drop functionality.              |
| **Chips with Form Control**| Integrate with Angular forms for two-way data binding.                       |
| **Chips with Input**       | Allow users to add new chips through an input field.                         |
| **Stacked Chips**          | Display chips in a stacked layout for a compact presentation.               |

## Installation

To use the drag-and-drop feature, ensure you have Angular CDK installed:

```bash
npm install @angular/cdk
```

Import the necessary module in your Angular module:

```typescript
import { DragDropModule } from '@angular/cdk/drag-drop';
```

## Basic Usage

| Property | Description                                     | Example                                 |
|----------|-------------------------------------------------|-----------------------------------------|
| `chips`  | Array of chip labels to display.                | `['Chip 1', 'Chip 2']`                  |

```html
<mtx-chips [chips]="['Chip 1', 'Chip 2']"></mtx-chips>
```

## Chips with Autocomplete

| Property          | Description                                   | Example                        |
|------------------ |----------------------------------------------- |--------------------------------|
| `autocompleteOptions` | Array of options for autocomplete.            | `['Option 1', 'Option 2']`     |

```html
<mtx-chips [chips]="['Chip 1']" [autocompleteOptions]="['Option 1', 'Option 2']"></mtx-chips>
```

## Chips with Avatar

| Property      | Description                                      | Example                          |
|---------------|-------------------------------------------------- |----------------------------------|
| `avatarUrls`  | Object mapping chip labels to avatar URLs.       | `{ 'Chip 1': 'avatar-url.jpg' }` |

```html
<mtx-chips [chips]="['Chip 1']" [avatarUrls]="{ 'Chip 1': 'avatar-url.jpg' }"></mtx-chips>
```

## Chips with Drag and Drop

| Property | Description                                   | Example                         |
|----------|----------------------------------------------- |---------------------------------|
| `isDrag` | Boolean flag to enable or disable drag-and-drop. | `true` or `false`               |

```html
<mtx-chips [chips]="['Chip 1', 'Chip 2']" [isDrag]="true"></mtx-chips>
```

## Chips with Form Control

| Property | Description                                   | Example                         |
|----------|----------------------------------------------- |---------------------------------|
| `formControlName` | Form control name for two-way data binding. | `'chipsControl'`               |

```html
<form [formGroup]="form">
  <mtx-chips [chips]="['Chip 1']" formControlName="chipsControl"></mtx-chips>
</form>
```

## Chips with Input

| Property          | Description                                     | Example                        |
|-------------------|-------------------------------------------------|--------------------------------|
| `inputEnabled`    | Boolean flag to enable or disable the input field for adding new chips. | `true` or `false` |

```html
<mtx-chips [chips]="['Chip 1']" [inputEnabled]="true"></mtx-chips>
```

## Stacked Chips

| Property | Description                                     | Example                        |
|----------|-------------------------------------------------|--------------------------------|
| `chips`  | Array of chip labels to display in a stacked layout. | `['Chip 1', 'Chip 2', 'Chip 3']` |

```html
<mtx-chips [chips]="['Chip 1', 'Chip 2', 'Chip 3']"></mtx-chips>
```

## Configuration

You can customize the appearance and behavior of the `MtxChips` component using the following configuration options:

| Option              | Description                                     | Default Value          |
|---------------------|-------------------------------------------------|------------------------|
| `backgroundColor`   | Sets the background color of the chips.         | `#e0e0e0`              |
| `chipColor`         | Sets the text color of the chips.               | `#000`                 |
| `removeIconColor`   | Sets the color of the remove icon.              | `#f00`                 |

### Example Configuration

```typescript
export interface MtxChipsConfig {
  backgroundColor?: string;
  chipColor?: string;
  removeIconColor?: string;
}

export const DEFAULT_MTX_CHIPS_CONFIG: MtxChipsConfig = {
  backgroundColor: '#e0e0e0',
  chipColor: '#000',
  removeIconColor: '#f00'
};
```

## MtxChips Component API

The `MtxChips` component provides a range of functionalities for displaying and interacting with chips. Below is a comprehensive guide to the component's API, including its inputs, outputs, methods, and configuration.

## Inputs

| Input                    | Type                          | Description                                                          | Default Value            |
|--------------------------|------------------------------- |----------------------------------------------------------------------|--------------------------|
| `chips`                  | `string[]`                     | List of chip labels to display.                                      | `[]`                     |
| `autocompleteOptions`    | `string[]`                     | Array of options for autocomplete functionality.                     | `[]`                     |
| `avatarUrls`             | `{ [key: string]: string }`   | Object mapping chip labels to avatar URLs.                           | `{}`                     |
| `isDrag`                 | `boolean`                      | Boolean flag to enable or disable drag-and-drop functionality.        | `false`                  |
| `inputEnabled`           | `boolean`                      | Boolean flag to enable or disable the input field for adding new chips. | `false`                  |
| `backgroundColor`        | `string`                       | Background color of the chips.                                       | `#e0e0e0`                |
| `chipColor`              | `string`                       | Text color of the chips.                                             | `#000`                   |
| `removeIconColor`        | `string`                       | Color of the remove icon.                                            | `#f00`                   |
| `formControlName`        | `string`                       | Form control name for two-way data binding.                           | `null`                   |

## Outputs

| Output                   | Type                          | Description                                                          |
|--------------------------|------------------------------- |----------------------------------------------------------------------|
| `chipRemoved`            | `EventEmitter<string>`         | Emitted when a chip is removed.                                     |
| `chipAdded`              | `EventEmitter<string>`         | Emitted when a new chip is added.                                   |
| `chipReordered`          | `EventEmitter<string[]>`       | Emitted when chips are reordered.                                  |

## Methods

| Method                   | Description                                              | Parameters      |
|--------------------------|---------------------------------------------------------- |-----------------|
| `removeChip(chip: string)` | Removes the specified chip from the list.                | `chip: string`  |
| `addChip(chip: string)`   | Adds a new chip to the list.                             | `chip: string`  |
| `reorderChips(chips: string[])` | Reorders chips based on the new order.                   | `chips: string[]`|

## Configuration Interface

The `MtxChipsConfig` interface allows you to customize the appearance and behavior of the `MtxChips` component.

```typescript
export interface MtxChipsConfig {
  backgroundColor?: string;
  chipColor?: string;
  removeIconColor?: string;
}
```

## Default Configuration

The default configuration for the `MtxChips` component is as follows:

```typescript
export const DEFAULT_MTX_CHIPS_CONFIG: MtxChipsConfig = {
  backgroundColor: '#e0e0e0',
  chipColor: '#000',
  removeIconColor: '#f00'
};
```

## Usage

### Basic Example

```html
<mtx-chips [chips]="['Chip 1', 'Chip 2']"></mtx-chips>
```

### Chips with Autocomplete

```html
<mtx-chips [chips]="['Chip 1']" [autocompleteOptions]="['Option 1', 'Option 2']"></mtx-chips>
```

### Chips with Avatar

```html
<mtx-chips [chips]="['Chip 1']" [avatarUrls]="{ 'Chip 1': 'avatar-url.jpg' }"></mtx-chips>
```

### Chips with Drag and Drop

```html
<mtx-chips [chips]="['Chip 1', 'Chip 2']" [isDrag]="true"></mtx-chips>
```

### Chips with Form Control

```html
<form [formGroup]="form">
  <mtx-chips [chips]="['Chip 1']" formControlName="chipsControl"></mtx-chips>
</form>
```

### Chips with Input

```html
<mtx-chips [chips]="['Chip 1']" [inputEnabled]="true"></mtx-chips>
```

### Stacked Chips

```html
<mtx-chips [chips]="['Chip 1', 'Chip 2', 'Chip 3']"></mtx-chips>
```

## Events

### `chipRemoved`

Emitted when a chip is removed.

```typescript
@Output() chipRemoved = new EventEmitter<string>();
```

### `chipAdded`

Emitted when a new chip is added.

```typescript
@Output() chipAdded = new EventEmitter<string>();
```

### `chipReordered`

Emitted when chips are reordered.

```typescript
@Output() chipReordered = new EventEmitter<string[]>();
```