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

## MtxAutocomplete Component Overview

The `MtxAutocomplete` Component is a custom Angular component that extends and encapsulates the Angular Material autocomplete component. It provides enhanced features like custom item templates, flexible client/server filtering, and compatibility with Angular forms API. This component is designed to improve the user experience by offering infinite scroll, keyboard navigation, debounce input for server requests, and more.

### Features

| Feature                      | Description                                                                 |
|------------------------------|-----------------------------------------------------------------------------|
| Custom Item and 'Not Found' Templates | Easily customize the display of items and the 'not found' message.             |
| Flexible Filtering           | Supports both client-side and server-side filtering.                        |
| Form Compatibility           | Works seamlessly with both Reactive and Template-driven forms.              |
| Infinite Scroll              | Load more items as the user scrolls down the list.                          |
| Keyboard Navigation          | Navigate through the options using the keyboard.                           |
| Debounce Input               | Reduce the number of server requests with input debouncing.                 |
| Clear Selection Button       | Allow users to clear their current selection with a button.                |
| Custom Error Handling        | Handle errors gracefully with custom error handling.                       |
| Styling Enhancements         | Style the component to match your application's look and feel.             |

### Usage

#### Installation
1. Import the `MtxAutocompleteModule` into your Angular module:

    ```typescript
    import { MtxAutocompleteModule } from '@ng-zi/extensions/autocomplete';

    @NgModule({
      declarations: [
        // your components
      ],
      imports: [
        // other modules
        MtxAutocompleteModule
      ],
      providers: [],
      bootstrap: [AppComponent]
    })
    export class AppModule { }
    ```

#### Example

##### Component TypeScript

```typescript
import { Component } from '@angular/core';

@Component({
  selector: 'app-autocomplete-demo',
  templateUrl: './autocomplete-demo.component.html'
})
export class AutocompleteDemoComponent {
  filteredItems: string[] = ['One', 'Two', 'Three'];

  autocompleteconfig = {
    options: this.filteredItems,
    placeholder: 'Search items',
    displayWith: (value: string) => value,
    debounceTime: 300,
    infiniteScrollThreshold: 0.8,
    serverFiltering: false,
    clearButton: true
  };

  onOptionSelected(value: string) {
    console.log('Option selected:', value);
  }

  onSearchChange(value: string) {
    console.log('Search changed:', value);
  }

  onErrorHandling(error: any) {
    console.error('Error occurred:', error);
  }
}
```

##### Component HTML

```html
<mtx-autocomplete 
  [autocompleteconfig]="autocompleteconfig" 
  (optionSelected)="onOptionSelected($event)" 
  (searchChange)="onSearchChange($event)" 
  (errorHandling)="onErrorHandling($event)">
</mtx-autocomplete>
```

### Configuration Options

| Option                  | Description                                                                                      |
|-------------------------|--------------------------------------------------------------------------------------------------|
| `options`               | The list of options to display in the autocomplete dropdown.                                      |
| `displayWith`           | A function to control how the options are displayed in the input field.                          |
| `placeholder`           | Placeholder text for the input field.                                                            |
| `debounceTime`          | Time in milliseconds to debounce input changes.                                                  |
| `infiniteScrollThreshold`| Threshold for triggering infinite scroll, as a decimal fraction of the viewport height.           |
| `serverFiltering`       | Whether to use server-side filtering for options.                                                |
| `clearButton`           | Whether to display a clear button to clear the selection.                                        |

### Events

| Event           | Description                                                    |
|-----------------|----------------------------------------------------------------|
| `optionSelected`| Event emitted when an option is selected.                      |
| `searchChange`  | Event emitted when the search input changes.                   |
| `errorHandling` | Event emitted when an error occurs.                            |

### Templates

| Template            | Description                                                      |
|---------------------|------------------------------------------------------------------|
| `notFoundTemplate`  | Template to display when no options are found.                   |
| `customItemTemplate`| Template to customize how options are displayed in the dropdown. |

### Custom Templates

You can customize the look and feel of the items and the 'not found' message using Angular's `ng-template` syntax.

#### Custom Item Template

```html
<ng-template #customItemTemplate let-item>
  <div class="custom-item">
    {{ item }}
  </div>
</ng-template>
```

#### Not Found Template

```html
<ng-template #notFoundTemplate>
  <div class="not-found">
    No items found.
  </div>
</ng-template>
```

#### Using Custom Templates

Pass the custom templates to the `MtxAutocompleteComponent` using the `autocompleteconfig` object:

```typescript
autocompleteconfig = {
  options: this.filteredItems,
  placeholder: 'Search items',
  customItemTemplate: this.customItemTemplate,
  notFoundTemplate: this.notFoundTemplate,
  debounceTime: 300,
  infiniteScrollThreshold: 0.8,
  serverFiltering: false,
  clearButton: true
};
```

```html
<mtx-autocomplete 
  [autocompleteconfig]="autocompleteconfig" 
  (optionSelected)="onOptionSelected($event)" 
  (searchChange)="onSearchChange($event)" 
  (errorHandling)="onErrorHandling($event)">
</mtx-autocomplete>

<ng-template #customItemTemplate let-item>
  <div class="custom-item">
    {{ item }}
  </div>
</ng-template>

<ng-template #notFoundTemplate>
  <div class="not-found">
    No items found.
  </div>
</ng-template>
```

#### Summary

The `MtxAutocomplete` Component provides a powerful and flexible way to implement autocomplete functionality in your Angular applications. With its customizable templates, filtering options, and seamless integration with Angular forms, it offers a rich user experience tailored to your needs.