feat(combos): extend filtering options

Author: wnvko

CHANGELOG.md

@@ -11,6 +11,11 @@ All notable changes for each version of this project will be documented in this
             {{ value.member }}
     </ng-template>
     ``` 
+### New Features
+- `IgxCombo` and  `IgxSimpleComboComponent`
+    - `filterFunction` input is added. The new property allows changing of the way filtering is done in the combos. By default filtering is made over the values in combo's data when it is a collection of primitive values, or over the values as defined in `displayKey` of the combo. If custom filtering function is provided filtering will be done as specified in the provided function.
+    - `filteringOptions` are extended and now contains `filterable` and `filteringKey` properties. Setting `filterable` determines whether combo will be filterable. By default filtering is done over the data value when they are primitive, or over the field of the values equal to `displayKey`. `filteringKey` allows to filter data by any data related key.
+    - **Breaking Changes** - `filterable` property of `IgxComboComponent` is now deprecated and will be removed in future version. Use `filteringOptions.filterable` instead.
 
 ## 14.0.0
 - `IgxDatePicker` and `IgxDateRangePicker` now expose a `weekStart` input property like the `IgxCalendar`

projects/igniteui-angular/src/lib/combo/README.md

@@ -322,6 +322,7 @@ Setting `[displayDensity]` affects the control's items' and inputs' css properti
 | `valid`               | gets if control is valid, when used in a form     | boolean                     |
 | `overlaySettings`     | gets/sets the custom overlay settings that control how the drop-down list displays | OverlaySettings |
 | `autoFocusSearch`     | controls whether the search input should be focused when the combo is opened | boolean |
+| `filteringOptions`    | Configures the way combo items will be filtered   | IComboFilteringOptions      |
 | `filterFunction`      | Gets/Sets the custom filtering function of the combo | `(collection: any[], searchValue: any, caseSensitive: boolean) => any[]` |
 
 ### Getters

projects/igniteui-angular/src/lib/combo/combo.common.ts

@@ -39,9 +39,7 @@ import {
     IgxComboAddItemDirective, IgxComboClearIconDirective, IgxComboEmptyDirective,
     IgxComboFooterDirective, IgxComboHeaderDirective, IgxComboHeaderItemDirective, IgxComboItemDirective, IgxComboToggleIconDirective
 } from './combo.directives';
-import {
-    IComboFilteringOptions, IComboItemAdditionEvent, IComboSearchInputEventArgs
-} from './public_api';
+import { IComboItemAdditionEvent, IComboSearchInputEventArgs } from './public_api';
 
 export const IGX_COMBO_COMPONENT = new InjectionToken<IgxComboBase>('IgxComboComponentToken');
 
@@ -114,6 +112,16 @@ export enum IgxComboState {
     INVALID = IgxInputState.INVALID
 }
 
+    /** The filtering criteria to be applied on data search */
+    export interface IComboFilteringOptions {
+        /** Defines filtering case-sensitivity */
+        caseSensitive: boolean;
+        /** Defines whether filtering is allowed */
+        filterable: boolean;
+        /** Defines optional key to filter against complex list items. Default to displayKey if provided.*/
+        filteringKey?: string;
+    }
+
 @Directive()
 export abstract class IgxComboBaseDirective extends DisplayDensityBase implements IgxComboBase, OnInit, DoCheck,
     AfterViewInit, OnDestroy, ControlValueAccessor {
@@ -395,13 +403,7 @@ export abstract class IgxComboBaseDirective extends DisplayDensityBase implement
      * ```
      */
      @Input()
-     public get filterFunction(): (collection: any[], searchValue: any, caseSensitive: boolean) => any[] {
-         return this._customFilterFunction;
-     }
- 
-     public set filterFunction(value: (collection: any[], searchValue: any, caseSensitive: boolean) => any[]) {
-         this._customFilterFunction = value;
-     }
+     public filterFunction: (collection: any[], searchValue: any, filteringOptions: IComboFilteringOptions) => any[];
 
     /**
      * An @Input property that set aria-labelledby attribute
@@ -858,12 +860,29 @@ export abstract class IgxComboBaseDirective extends DisplayDensityBase implement
     /** @hidden @internal */
     public defaultFallbackGroup = 'Other';
     /** @hidden @internal */
-    public filteringOptions: IComboFilteringOptions = {
-        caseSensitive: false
-    };
-    /** @hidden @internal */
     public activeDescendant = '';
 
+    /**
+     * Configures the way combo items will be filtered.
+     *
+     * ```typescript
+     * // get
+     * let myFilteringOptions = this.combo.filteringOptions;
+     * ```
+     *
+     * ```html
+     * <!--set-->
+     * <igx-combo [filteringOptions]='myFilteringOptions'></igx-combo>
+     * ```
+     */
+
+     @Input()
+     public get filteringOptions(): IComboFilteringOptions {
+         return this._filteringOptions || this._defaultFilteringOptions;
+     }
+     public set filteringOptions(value: IComboFilteringOptions) {
+         this._filteringOptions = value;
+     }
     protected _data = [];
     protected _value = '';
     protected _groupKey = '';
@@ -883,8 +902,8 @@ export abstract class IgxComboBaseDirective extends DisplayDensityBase implement
     private _itemsMaxHeight = null;
     private _overlaySettings: OverlaySettings;
     private _groupSortingDirection: SortingDirection = SortingDirection.Asc;
-    private _customFilterFunction: (collection: any[], searchValue: any, caseSensitive: boolean) => any[] = null;
-
+    private _filteringOptions: IComboFilteringOptions;
+    private _defaultFilteringOptions: IComboFilteringOptions = { caseSensitive: false, filterable: true };
     public abstract dropdown: IgxComboDropDownComponent;
 
     public abstract selectionChanging: EventEmitter<any>;
@@ -1160,7 +1179,7 @@ export abstract class IgxComboBaseDirective extends DisplayDensityBase implement
 
     /** @hidden @internal */
     public toggleCaseSensitive() {
-        this.filteringOptions = { caseSensitive: !this.filteringOptions.caseSensitive };
+        this.filteringOptions = Object.assign({}, this.filteringOptions, { caseSensitive: !this.filteringOptions.caseSensitive });
     }
 
     protected onStatusChanged = () => {

projects/igniteui-angular/src/lib/combo/combo.component.html

@@ -57,7 +57,7 @@
         [tabindex]="dropdown.collapsed ? -1 : 0" [attr.id]="dropdown.id" aria-multiselectable="true"
         [attr.aria-activedescendant]="this.activeDescendant">
         <igx-combo-item [itemHeight]='itemHeight' *igxFor="let item of data
-            | comboFiltering:filterFunction:filterValue:filteringOptions:filterable:displayKey
+            | comboFiltering:filterValue:displayKey:filteringOptions:filterFunction
             | comboGrouping:groupKey:valueKey:groupSortingDirection;
             index as rowIndex; containerSize: itemsMaxHeight; scrollOrientation: 'vertical'; itemSize: itemHeight"
             [value]="item" [isHeader]="item.isHeader" [index]="rowIndex" [role]="item.isHeader? 'group' : 'option'">

projects/igniteui-angular/src/lib/combo/combo.component.spec.ts

@@ -1,35 +1,33 @@
-import { AfterViewInit, ChangeDetectorRef, Component, Injectable, OnInit, ViewChild, OnDestroy, DebugElement } from '@angular/core';
-import { TestBed, tick, fakeAsync, ComponentFixture, waitForAsync } from '@angular/core/testing';
+import { AfterViewInit, ChangeDetectorRef, Component, DebugElement, Injectable, OnDestroy, OnInit, ViewChild } from '@angular/core';
+import { ComponentFixture, fakeAsync, TestBed, tick, waitForAsync } from '@angular/core/testing';
+import {
+    FormsModule, NgControl, NgForm, NgModel, ReactiveFormsModule, UntypedFormBuilder, UntypedFormControl, UntypedFormGroup, Validators
+} from '@angular/forms';
 import { By } from '@angular/platform-browser';
 import { NoopAnimationsModule } from '@angular/platform-browser/animations';
-import { UntypedFormGroup, UntypedFormControl, Validators, UntypedFormBuilder, ReactiveFormsModule,
-    FormsModule, NgControl, NgModel, NgForm } from '@angular/forms';
-import {
-    IgxComboComponent,
-    IgxComboModule,
-    IComboSelectionChangingEventArgs,
-    IComboSearchInputEventArgs,
-    IComboItemAdditionEvent
-} from './combo.component';
-import { IgxComboItemComponent } from './combo-item.component';
-import { IgxComboDropDownComponent } from './combo-dropdown.component';
-import { IgxComboAddItemComponent } from './combo-add-item.component';
-import { IgxComboFilteringPipe } from './combo.pipes';
-import { IgxInputState } from '../directives/input/input.directive';
-import { IForOfState } from '../directives/for-of/for_of.directive';
-import { IgxToggleModule } from '../directives/toggle/toggle.directive';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { take } from 'rxjs/operators';
-import { UIInteractions, wait } from '../test-utils/ui-interactions.spec';
-import { configureTestSuite } from '../test-utils/configure-suite';
 import { DisplayDensity } from '../core/density';
-import { AbsoluteScrollStrategy, ConnectedPositioningStrategy } from '../services/public_api';
 import { IgxSelectionAPIService } from '../core/selection';
-import { IgxIconService } from '../icon/public_api';
 import { IBaseCancelableBrowserEventArgs } from '../core/utils';
 import { SortingDirection } from '../data-operations/sorting-strategy';
-import { IgxComboState } from './combo.common';
+import { IForOfState } from '../directives/for-of/for_of.directive';
+import { IgxInputState } from '../directives/input/input.directive';
+import { IgxToggleModule } from '../directives/toggle/toggle.directive';
 import { IgxDropDownItemBaseDirective } from '../drop-down/public_api';
+import { IgxIconService } from '../icon/public_api';
+import { AbsoluteScrollStrategy, ConnectedPositioningStrategy } from '../services/public_api';
+import { configureTestSuite } from '../test-utils/configure-suite';
+import { UIInteractions, wait } from '../test-utils/ui-interactions.spec';
+import { IgxComboAddItemComponent } from './combo-add-item.component';
+import { IgxComboDropDownComponent } from './combo-dropdown.component';
+import { IgxComboItemComponent } from './combo-item.component';
+import { IComboFilteringOptions, IgxComboState } from './combo.common';
+import {
+    IComboItemAdditionEvent, IComboSearchInputEventArgs, IComboSelectionChangingEventArgs, IgxComboComponent,
+    IgxComboModule
+} from './combo.component';
+import { IgxComboFilteringPipe } from './combo.pipes';
 
 const CSS_CLASS_COMBO = 'igx-combo';
 const CSS_CLASS_COMBO_DROPDOWN = 'igx-combo__drop-down';
@@ -2689,14 +2687,14 @@ describe('igxCombo', () => {
             combo.close();
             tick();
             fixture.detectChanges();
-            // set filter function to search only on valueKyes
-            combo.filterFunction = (collection: any[], searchValue: any): any[] => {
+            combo.filteringOptions = { caseSensitive: false, filterable: true, filteringKey: combo.groupKey };
+            combo.filterFunction = (collection: any[], searchValue: any, filteringOptions: IComboFilteringOptions): any[] => {
                 if (!collection) return [];
                 if (!searchValue) return collection;
-                const searchTerm = combo.filteringOptions.caseSensitive ? searchValue.trim() : searchValue.toLowerCase().trim();
-                return collection.filter(i => combo.filteringOptions.caseSensitive ?
-                    i[combo.displayKey]?.includes(searchTerm) || i[combo.groupKey]?.includes(searchTerm) :
-                    i[combo.displayKey]?.toString().toLowerCase().includes(searchTerm) || i[combo.groupKey]?.toString().toLowerCase().includes(searchTerm))
+                const searchTerm = filteringOptions.caseSensitive ? searchValue.trim() : searchValue.toLowerCase().trim();
+                return collection.filter(i => filteringOptions.caseSensitive ?
+                    i[filteringOptions.filteringKey]?.includes(searchTerm) :
+                    i[filteringOptions.filteringKey]?.toString().toLowerCase().includes(searchTerm))
                 }
             combo.open();
             tick();
@@ -2708,11 +2706,12 @@ describe('igxCombo', () => {
             fixture.detectChanges();
             expect(combo.dropdown.items.length).toBeGreaterThan(0);
 
-            combo.filterFunction = null;
+            combo.filterFunction = undefined;
+            combo.filteringOptions = undefined;
             fixture.detectChanges();
             expect(combo.dropdown.items.length).toEqual(0);
         }));
-        it('Should update filtering when custom filterFunction is provided and filteringOptions are changed', fakeAsync(() => {
+        it('Should update filtering when custom filterFunction is provided and filteringOptions.caseSensitive is changed', fakeAsync(() => {
             combo.open();
             tick();
             fixture.detectChanges();
@@ -2726,14 +2725,14 @@ describe('igxCombo', () => {
             combo.close();
             tick();
             fixture.detectChanges();
-            // set filter function to search only on valueKyes
-            combo.filterFunction = (collection: any[], searchValue: any): any[] => {
+            combo.filteringOptions = { caseSensitive: false, filterable: true, filteringKey: combo.groupKey };
+            combo.filterFunction = (collection: any[], searchValue: any, filteringOptions: IComboFilteringOptions): any[] => {
                 if (!collection) return [];
                 if (!searchValue) return collection;
-                const searchTerm = combo.filteringOptions.caseSensitive ? searchValue.trim() : searchValue.toLowerCase().trim();
-                return collection.filter(i => combo.filteringOptions.caseSensitive ?
-                    i[combo.displayKey]?.includes(searchTerm) || i[combo.groupKey]?.includes(searchTerm) :
-                    i[combo.displayKey]?.toString().toLowerCase().includes(searchTerm) || i[combo.groupKey]?.toString().toLowerCase().includes(searchTerm))
+                const searchTerm = filteringOptions.caseSensitive ? searchValue.trim() : searchValue.toLowerCase().trim();
+                return collection.filter(i => filteringOptions.caseSensitive ?
+                    i[filteringOptions.filteringKey]?.includes(searchTerm) :
+                    i[filteringOptions.filteringKey]?.toString().toLowerCase().includes(searchTerm))
                 }
             combo.open();
             tick();
@@ -2745,11 +2744,11 @@ describe('igxCombo', () => {
             fixture.detectChanges();
             expect(combo.dropdown.items.length).toBeGreaterThan(0);
 
-            combo.filteringOptions = { caseSensitive: true };
+            combo.filteringOptions = Object.assign({}, combo.filteringOptions, { caseSensitive: true });
             fixture.detectChanges();
             expect(combo.dropdown.items.length).toEqual(0);
         }));
-        it('Should update filtering when custom filterFunction is provided and filterable is changed', fakeAsync(() => {
+        it('Should update filtering when custom filteringOptions are provided', fakeAsync(() => {
             combo.open();
             tick();
             fixture.detectChanges();
@@ -2763,15 +2762,7 @@ describe('igxCombo', () => {
             combo.close();
             tick();
             fixture.detectChanges();
-            // set filter function to search only on valueKyes
-            combo.filterFunction = (collection: any[], searchValue: any): any[] => {
-                if (!collection) return [];
-                if (!searchValue) return collection;
-                const searchTerm = combo.filteringOptions.caseSensitive ? searchValue.trim() : searchValue.toLowerCase().trim();
-                return collection.filter(i => combo.filteringOptions.caseSensitive ?
-                    i[combo.displayKey]?.includes(searchTerm) || i[combo.groupKey]?.includes(searchTerm) :
-                    i[combo.displayKey]?.toString().toLowerCase().includes(searchTerm) || i[combo.groupKey]?.toString().toLowerCase().includes(searchTerm))
-                }
+            combo.filteringOptions = { caseSensitive: false, filterable: true, filteringKey: combo.groupKey };
             combo.open();
             tick();
             fixture.detectChanges();
@@ -2787,7 +2778,7 @@ describe('igxCombo', () => {
             fixture.detectChanges();
             expect(combo.dropdown.items.length).toEqual(0);
 
-            combo.filterable = false;
+            combo.filteringOptions = Object.assign({}, combo.filteringOptions, { filterable: false });
             fixture.detectChanges();
             expect(combo.dropdown.items.length).toBeGreaterThan(0);
         }));

projects/igniteui-angular/src/lib/combo/combo.component.ts

@@ -36,12 +36,6 @@ import { IgxComboAPIService } from './combo.api';
 import { EditorProvider } from '../core/edit-provider';
 import { IgxInputGroupType, IGX_INPUT_GROUP_TYPE } from '../input-group/public_api';
 
-/** The filtering criteria to be applied on data search */
-export interface IComboFilteringOptions {
-    /** Defines filtering case-sensitivity */
-    caseSensitive: boolean;
-}
-
 /** Event emitted when an igx-combo's selection is changing */
 export interface IComboSelectionChangingEventArgs extends IBaseCancelableEventArgs {
     /** An array containing the values that are currently selected */
@@ -124,13 +118,20 @@ export class IgxComboComponent extends IgxComboBaseDirective implements AfterVie
     public autoFocusSearch = true;
 
     /**
+     * @deprecated in version 14.0.0. Use the IComboFilteringOptions.filterable
+     * 
      * An @Input property that enabled/disables filtering in the list. The default is `true`.
      * ```html
      * <igx-combo [filterable]="false">
      * ```
      */
     @Input()
-    public filterable = true;
+    public get filterable(): boolean {
+        return this.filteringOptions.filterable;
+    }
+    public set filterable(value: boolean) {
+        this.filteringOptions = Object.assign({}, this.filteringOptions, { filterable: value });
+    }
 
     /**
      * Defines the placeholder value for the combo dropdown search field
@@ -171,7 +172,7 @@ export class IgxComboComponent extends IgxComboBaseDirective implements AfterVie
 
     /** @hidden @internal */
     public get filteredData(): any[] | null {
-        return this.filterable ? this._filteredData : this.data;
+        return this.filteringOptions.filterable ? this._filteredData : this.data;
     }
     /** @hidden @internal */
     public set filteredData(val: any[] | null) {
@@ -203,7 +204,7 @@ export class IgxComboComponent extends IgxComboBaseDirective implements AfterVie
 
     /** @hidden @internal */
     public get displaySearchInput(): boolean {
-        return this.filterable || this.allowCustomValues;
+        return this.filteringOptions.filterable || this.allowCustomValues;
     }
 
     /**