Generic Auto Complete

The GenericAutoCompleteComponent is a reusable Angular component that provides an enhanced auto-complete input field. It allows users to search and select from a list of options, with support for dynamic data fetching, validation, and custom configurations. This component is ideal for scenarios where users need to search, filter, and select values dynamically.

How to use the component in your app :

1. import the component :

import {GenericAutoCompleteComponent} from '@tradinos/cms-frontend-form';

1. The selector for component , like it :

<lib-cms-generic-auto-complete></lib-cms-generic-auto-complete>

Features

1. Dynamic Suggestions:

   • Dynamically updates the list of suggestions based on user input.

2. Remote Data Management:

   • Fetches options from remote data sources via API endpoints with support for query parameters and response mapping.

3. Static and Grouped Data Support:

   • Works with both flat and grouped datasets.

   • Supports grouped suggestions for categorized data.

4. Caching:

   • Utilizes caching to reduce redundant API requests and improve performance for repeated searches.

5. Customizable Filtering:

   • Implements flexible filtering logic for static and remote datasets using the filterBy configuration option.

6. Live Search:

   • Implements a search method to filter suggestions dynamically as the user types.

7. Reactivity:

   • Listens to reactive streams (index$) to dynamically update options or reset selections when triggered externally.

8. Event-Driven:

   • Emits optionChange and valueChange events for integration with parent components, enabling real-time updates and feedback.

9. Dynamic Option Selection:

   • Automatically selects options based on pre-configured indices or custom logic (indexFn), supporting both single and multiple selection modes.

10. Error Handling:

    • Handles invalid states and gracefully manages missing or incomplete configurations.

11. Configurable Behavior:

    • Fully customizable through an AutoCompleteConfiguration object, allowing developers to tailor the component to specific needs.

Inputs

Input	Type	Description	Default Value
configuration	AutoCompleteConfiguration	Configuration object defining behavior, filtering, labels, and data sources for the auto-complete.	-
disabled	boolean | null	Controls whether the auto-complete input is disabled.	null
option	any	The currently selected option.	-
invalid	boolean	Indicates if the auto-complete input is in an invalid state.	false

This the options in AutoCompleteConfiguration type:

{
  multiple?: boolean;
  dropdown?: boolean;
  showClear?: boolean;
  filterBy: string;
  optionLabel: string;
  options: any[];
  optionsFn?: () => any[];
  valueBy: string;
  remoteDataConfiguration?: RemoteDataConfiguration;//find it below
  index?: number | number[];
  index$?: BehaviorSubject<number | number[] | undefined>;
  indexFn?: (items: any[]) => number | number[];
  onChange?: (value: any) => void;
  template?: OptionTemplate;
  group?: boolean;
}

For example:

{
filterBy: 'label',
    optionLabel: '',
    valueBy: 'value',
    group: true,
    options: [
        {
            label: 'Germany', value: 'de',
            items: [
                { label: 'Berlin', value: 'Berlin' },
                { label: 'Frankfurt', value: 'Frankfurt' },
            ]
        },
        {
            label: 'USA', value: 'us',
            items: [
                { label: 'Chicago', value: 'Chicago' },
                { label: 'Los Angeles', value: 'Los Angeles' },
            ]
        },
    ],
}

This is the RemoteDataConfiguration type:

//use event-emitter emit dropdown re-fetch data with new endPoint 
//use this when this dropdown depend on dynamic endPoint parameters 
//like (id, query)
{
  endPoint?: string;
  queryParams?: any;
  cache?: boolean;
  endPoint$?: EventEmitter<{ url: string; queryParams?: any; clearCache?: boolean }>;
  mapHttpResponse: <T>(response: any) => T[];
}

Methods

1. ngOnInit()

• Description:

  • Initializes the component and sets up the options from static, remote, or functional data sources.

  • Configures reactive streams for real-time updates.

• Parameters: None.

• Returns: void.

2. search(event: AutoCompleteCompleteEvent): void

• Description:

  • Dynamically filters suggestions based on the user’s input.

  • Uses local filtering for static data or sends API requests for remote filtering.

• Parameters:

  • event: Contains the search query (event.query) entered by the user.

• Behavior:

  • Filters the configuration.options array locally.

  • Fetches suggestions remotely if remoteDataConfiguration is defined.

3. fetchOptions(endPoint?: string, queryParams?: any): void

• Description:

  • Fetches options from a specified API endpoint and updates the suggestions list.

  • Applies response mapping and caching if configured.

• Parameters:

  • endPoint (optional): The API endpoint URL to fetch data from.

  • queryParams (optional): Additional query parameters for the API request.

4. selectIndex(value?: number | number[]): void

• Description:

  • Selects one or more options based on predefined indices or a custom selection logic (indexFn).

  • Supports both single and multiple selection modes.

• Parameters:

  • value (optional): Index or indices to pre-select options.

• Behavior:

  • Single Mode: Selects a single option based on the provided index.

  • Multiple Mode: Selects multiple options based on an array of indices.

5. onChange(event: any | any[]): void

• Description:

  • Emits optionChange and valueChange events to notify the parent component of the selected option or value.

• Parameters:

  • event: The currently selected option(s).

• Behavior:

  • Emits the selected option object via optionChange.

  • Emits the corresponding value (based on valueBy) via valueChange.

Features

The GenericAutoCompleteComponent comes packed with the following features:

1. Dynamic Suggestions:

   • Dynamically updates the list of suggestions based on user input.

2. Remote Data Management:

   • Fetches options from remote data sources via API endpoints with support for query parameters and response mapping.

3. Static and Grouped Data Support:

   • Works with both flat and grouped datasets.

   • Supports grouped suggestions for categorized data.

4. Caching:

   • Utilizes caching to reduce redundant API requests and improve performance for repeated searches.

5. Customizable Filtering:

   • Implements flexible filtering logic for static and remote datasets using the filterBy configuration option.

6. Live Search:

   • Implements a search method to filter suggestions dynamically as the user types.

7. Reactivity:

   • Listens to reactive streams (index$) to dynamically update options or reset selections when triggered externally.

8. Event-Driven:

   • Emits optionChange and valueChange events for integration with parent components, enabling real-time updates and feedback.

9. Dynamic Option Selection:

   • Automatically selects options based on pre-configured indices or custom logic (indexFn), supporting both single and multiple selection modes.

10. Error Handling:

    • Handles invalid states and gracefully manages missing or incomplete configurations.

11. Configurable Behavior:

    • Fully customizable through an AutoCompleteConfiguration object, allowing developers to tailor the component to specific needs.

Methods

1. ngOnInit()

• Description:

  • Initializes the component and sets up the options from static, remote, or functional data sources.

  • Configures reactive streams for real-time updates.

• Parameters: None.

2. search(event: AutoCompleteCompleteEvent): void

• Description:

  • Dynamically filters suggestions based on the user’s input.

  • Uses local filtering for static data or sends API requests for remote filtering.

• Parameters:

  • event: Contains the search query (event.query) entered by the user.

• Behavior:

  • Filters the configuration.options array locally.

  • Fetches suggestions remotely if remoteDataConfiguration is defined.

3. fetchOptions(endPoint?: string, queryParams?: any): void

• Description:

  • Fetches options from a specified API endpoint and updates the suggestions list.

  • Applies response mapping and caching if configured.

• Parameters:

  • endPoint (optional): The API endpoint URL to fetch data from.

  • queryParams (optional): Additional query parameters for the API request.

• Returns: void.

4. selectIndex(value?: number | number[]): void

• Description:

  • Selects one or more options based on predefined indices or a custom selection logic (indexFn).

  • Supports both single and multiple selection modes.

• Parameters:

  • value (optional): Index or indices to pre-select options.

• Behavior:

  • Single Mode: Selects a single option based on the provided index.

  • Multiple Mode: Selects multiple options based on an array of indices.

• Returns: void.

5. onChange(event: any | any[]): void

• Description:

  • Emits optionChange and valueChange events to notify the parent component of the selected option or value.

• Parameters:

  • event: The currently selected option(s).

• Behavior:

  • Emits the selected option object via optionChange.

  • Emits the corresponding value (based on valueBy) via valueChange.

6. filter(result: any[], event?: AutoCompleteCompleteEvent): void

• Description:

  • Filters the provided options based on the search query (event.query) or updates suggestions directly from a dataset.

• Parameters:

  • result: The dataset to filter.

  • event (optional): The search query entered by the user.

• Behavior:

  • Grouped Data: Filters items within groups and maintains their structure.

  • Flat Data: Filters items directly.