feat(combo): add display text overwrite to selection change event, #6342

Author: ViktorSlavov

CHANGELOG.md

@@ -83,6 +83,23 @@ All notable changes for each version of this project will be documented in this
 - `IgxSelect`: 
     - adding `IgxSelectHeaderDirective` and `IgxSelectFooterDirective`. These can be used to provide a custom header, respectively footer templates for the `igxSelect` drop-down list. If there are no templates marked with these directives - no default templates will be used so the drop-down list will not have header nor footer.
 
+- `IgxCombo`:
+    - Added `textValue` property to the combo's `onSelectionChange` event args. The property contains the text that will be populated in the combo's text box **after** selection completes. This text can be overwritten in order to display a custom message, e.g. "3 items selected":
+    ```html
+    <igx-combo [data]="people" valueKey="id" displayKey="name" placeholder="Invite friends..." (onSelectionChange)="handleSelection($event)">
+    ```
+    ```typescript
+    export class MyInvitationComponent {
+        public people: { name: string; id: string }[] = [...];
+        ...
+        handleSelection(event: IComboSelectionChangeEventArgs) {
+            const count = event.newSelection.length;
+            event.textValue = count > 0 ? `${count} friend${count > 1 ? 's' : ''} invited!` : `No friends invited :(`;
+        }
+        ...
+    }
+    ```
+
 - `IgxDropDown`:
     - `clearSelection` method is added, which can be used to deselect the selected dropdown item
 

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

@@ -1020,6 +1020,7 @@ describe('igxCombo', () => {
                 newSelection: [targetItem.itemID],
                 added: [targetItem.itemID],
                 removed: [],
+                textValue: `${targetItem.value[combo.displayKey]}`,
                 event: undefined,
                 cancel: false
             });
@@ -1034,6 +1035,7 @@ describe('igxCombo', () => {
                 newSelection: [],
                 added: [],
                 removed: [targetItem.itemID],
+                textValue: '',
                 event: undefined,
                 cancel: false
             });
@@ -1045,57 +1047,61 @@ describe('igxCombo', () => {
             spyOn(combo.onSelectionChange, 'emit');
             let oldSelection = [];
             let newSelection = [combo.data[1], combo.data[5], combo.data[6]];
+            let newSelectionKeys = newSelection.map(entry => entry[combo.valueKey]);
 
             combo.toggle();
             tick();
             fix.detectChanges();
-            combo.selectItems(newSelection);
+            combo.selectItems(newSelectionKeys);
             fix.detectChanges();
             expect(combo.selectedItems().length).toEqual(newSelection.length);
             expect(combo.onSelectionChange.emit).toHaveBeenCalledTimes(1);
             expect(combo.onSelectionChange.emit).toHaveBeenCalledWith({
                 oldSelection: oldSelection,
-                newSelection: newSelection,
-                added: [combo.data[1], combo.data[5], combo.data[6]],
+                newSelection: newSelectionKeys,
+                added: newSelectionKeys,
                 removed: [],
+                textValue: newSelection.map(entry => entry[combo.valueKey]).join(', '),
                 event: undefined,
                 cancel: false
             });
 
             let newItem = combo.data[3];
-            combo.selectItems([newItem]);
-            oldSelection = [...newSelection];
-            newSelection.push(newItem);
+            combo.selectItems([newItem[combo.valueKey]]);
+            oldSelection = [...newSelectionKeys];
+            newSelectionKeys.push(newItem[combo.valueKey]);
             fix.detectChanges();
-            expect(combo.selectedItems().length).toEqual(newSelection.length);
+            expect(combo.selectedItems().length).toEqual(newSelectionKeys.length);
             expect(combo.onSelectionChange.emit).toHaveBeenCalledTimes(2);
             expect(combo.onSelectionChange.emit).toHaveBeenCalledWith({
                 oldSelection: oldSelection,
-                newSelection: newSelection,
+                newSelection: newSelectionKeys,
                 removed: [],
-                added: [combo.data[3]],
+                added: [newItem[combo.valueKey]],
+                textValue: newSelectionKeys.join(', '),
                 event: undefined,
                 cancel: false
             });
 
-            oldSelection = [...newSelection];
-            newSelection = [combo.data[0]];
-            combo.selectItems(newSelection, true);
+            oldSelection = [...newSelectionKeys];
+            newSelectionKeys = [combo.data[0][combo.valueKey]];
+            combo.selectItems(newSelectionKeys, true);
             fix.detectChanges();
-            expect(combo.selectedItems().length).toEqual(newSelection.length);
+            expect(combo.selectedItems().length).toEqual(newSelectionKeys.length);
             expect(combo.onSelectionChange.emit).toHaveBeenCalledTimes(3);
             expect(combo.onSelectionChange.emit).toHaveBeenCalledWith({
                 oldSelection: oldSelection,
-                newSelection: newSelection,
+                newSelection: newSelectionKeys,
                 removed: oldSelection,
-                added: [combo.data[0]],
+                added: [combo.data[0][combo.valueKey]],
+                textValue: combo.data[0][combo.valueKey],
                 event: undefined,
                 cancel: false
             });
 
-            oldSelection = [...newSelection];
+            oldSelection = [...newSelectionKeys];
             newSelection = [];
-            newItem = combo.data[0];
+            newItem = combo.data[0][combo.valueKey];
             combo.deselectItems([newItem]);
             fix.detectChanges();
             expect(combo.selectedItems().length).toEqual(newSelection.length);
@@ -1104,7 +1110,8 @@ describe('igxCombo', () => {
             expect(combo.onSelectionChange.emit).toHaveBeenCalledWith({
                 oldSelection: oldSelection,
                 newSelection: newSelection,
-                removed: [combo.data[0]],
+                removed: [newItem],
+                textValue: ``,
                 added: [],
                 event: undefined,
                 cancel: false
@@ -1422,11 +1429,12 @@ describe('igxCombo', () => {
             const dropdown = combo.dropdown;
             let timesFired = 1;
             const mockEvent = new MouseEvent('click');
-            const eventParams = {
+            const eventParams: IComboSelectionChangeEventArgs = {
                 oldSelection: [],
                 newSelection: [],
                 added: [],
                 removed: [],
+                textValue: '',
                 event: mockEvent,
                 cancel: false
             };
@@ -1446,12 +1454,14 @@ describe('igxCombo', () => {
 
             eventParams.newSelection = [dropdown.items[3].value];
             eventParams.added = [dropdown.items[3].value];
+            eventParams.textValue = dropdown.items[3].value;
             verifyOnSelectionChangeEventIsFired(3);
             timesFired++;
 
             eventParams.oldSelection = [dropdown.items[3].value];
             eventParams.newSelection = [dropdown.items[3].value, dropdown.items[7].value];
             eventParams.added = [dropdown.items[7].value];
+            eventParams.textValue = `${dropdown.items[3].value}, ${dropdown.items[7].value}`;
             verifyOnSelectionChangeEventIsFired(7);
             timesFired++;
 
@@ -1460,6 +1470,7 @@ describe('igxCombo', () => {
             eventParams.newSelection = [dropdown.items[3].value];
             eventParams.added = [];
             eventParams.removed = [dropdown.items[7].value];
+            eventParams.textValue = dropdown.items[3].value;
             verifyOnSelectionChangeEventIsFired(7);
         }));
         it('Should be able to select item when in grouped state', fakeAsync(() => {
@@ -1593,56 +1604,67 @@ describe('igxCombo', () => {
             fixture.detectChanges();
             const combo = fixture.componentInstance.combo;
             const selectionSpy = spyOn(fixture.componentInstance, 'onSelectionChange');
-            const expectedResults = {
-                newSelection: [combo.data[0]],
+            const expectedResults: IComboSelectionChangeEventArgs = {
+                newSelection: [combo.data[0][combo.valueKey]],
                 oldSelection: [],
-                added: [combo.data[0]],
+                added: [combo.data[0][combo.valueKey]],
                 removed: [],
                 event: undefined,
+                textValue: `${combo.data[0][combo.displayKey]}`,
                 cancel: false
             };
-            combo.selectItems([combo.data[0]]);
+            combo.selectItems([combo.data[0][combo.valueKey]]);
             expect(selectionSpy).toHaveBeenCalledWith(expectedResults);
             Object.assign(expectedResults, {
                 newSelection: [],
-                oldSelection: [combo.data[0]],
+                oldSelection: [combo.data[0][combo.valueKey]],
                 added: [],
-                removed: [combo.data[0]]
+                textValue: '',
+                removed: [combo.data[0][combo.valueKey]]
             });
-            combo.deselectItems([combo.data[0]]);
+            combo.deselectItems([combo.data[0][combo.valueKey]]);
             expect(selectionSpy).toHaveBeenCalledWith(expectedResults);
         });
 
         it('Should properly emit added and removed values in change event - multiple values', () => {
             const fixture = TestBed.createComponent(IgxComboSampleComponent);
             fixture.detectChanges();
             const combo = fixture.componentInstance.combo;
+            let oldSelection = [];
+            let newSelection = [combo.data[0], combo.data[1], combo.data[2]];
             const selectionSpy = spyOn(fixture.componentInstance, 'onSelectionChange');
-            const expectedResults = {
-                newSelection: [combo.data[0], combo.data[1], combo.data[2]],
-                oldSelection: [],
-                added: [combo.data[0], combo.data[1], combo.data[2]],
+            const expectedResults: IComboSelectionChangeEventArgs = {
+                newSelection: newSelection.map(e => e[combo.valueKey]),
+                oldSelection,
+                added: newSelection.map(e => e[combo.valueKey]),
                 removed: [],
                 event: undefined,
+                textValue: `${newSelection.map(entry => entry[combo.displayKey]).join(', ')}`,
                 cancel: false
             };
-            combo.selectItems([combo.data[0], combo.data[1], combo.data[2]]);
+            combo.selectItems(newSelection.map(e => e[combo.valueKey]));
             expect(selectionSpy).toHaveBeenCalledWith(expectedResults);
-            combo.deselectItems([combo.data[0]]);
+            oldSelection = [...newSelection].map(e => e[combo.valueKey]);
+            newSelection = [combo.data[1], combo.data[2]];
+            combo.deselectItems([combo.data[0][combo.valueKey]]);
             Object.assign(expectedResults, {
-                newSelection: [combo.data[1], combo.data[2]],
-                oldSelection: [combo.data[0], combo.data[1], combo.data[2]],
+                newSelection: newSelection.map(e => e[combo.valueKey]),
+                oldSelection,
                 added: [],
-                removed: [combo.data[0]]
+                textValue: newSelection.map(e => e[combo.displayKey]).join(', '),
+                removed: [combo.data[0][combo.valueKey]]
             });
+            oldSelection = [...newSelection].map(e => e[combo.valueKey]);
+            newSelection = [combo.data[4], combo.data[5], combo.data[6]];
             expect(selectionSpy).toHaveBeenCalledWith(expectedResults);
             Object.assign(expectedResults, {
-                newSelection: [combo.data[4], combo.data[5], combo.data[6]],
-                oldSelection: [combo.data[1], combo.data[2]],
-                added: [combo.data[4], combo.data[5], combo.data[6]],
-                removed: [combo.data[1], combo.data[2]]
+                newSelection: newSelection.map(e => e[combo.valueKey]),
+                oldSelection,
+                added: newSelection.map(e => e[combo.valueKey]),
+                textValue: newSelection.map(e => e[combo.displayKey]).join(', '),
+                removed: oldSelection
             });
-            combo.selectItems([combo.data[4], combo.data[5], combo.data[6]], true);
+            combo.selectItems(newSelection.map(e => e[combo.valueKey]), true);
             expect(selectionSpy).toHaveBeenCalledWith(expectedResults);
         });
     });

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

@@ -91,6 +91,10 @@ export interface IComboSelectionChangeEventArgs extends CancelableEventArgs, IBa
     added: any[];
     /** An array containing the values that will be removed from the selection (if any) */
     removed: any[];
+    /** The text that will be displayed in the combo text box
+     * If the combo is **remote**, this will be empty
+     */
+    textValue: string;
     /** The user interaction that triggered the selection change */
     event?: Event;
 }
@@ -1382,12 +1386,15 @@ export class IgxComboComponent extends DisplayDensityBase implements IgxComboBas
     protected setSelection(newSelection: Set<any>, event?: Event): void {
         const removed = diffInSets(this.selection.get(this.id), newSelection);
         const added = diffInSets(newSelection, this.selection.get(this.id));
+        const newSelectionAsArray = Array.from(newSelection);
+        const text = this.concatTextValue(newSelectionAsArray);
         const args: IComboSelectionChangeEventArgs = {
-            newSelection: Array.from(newSelection),
+            newSelection: newSelectionAsArray,
             oldSelection: Array.from(this.selection.get(this.id) || []),
             added,
             removed,
             event,
+            textValue: text,
             cancel: false
         };
         this.onSelectionChange.emit(args);
@@ -1415,6 +1422,17 @@ export class IgxComboComponent extends DisplayDensityBase implements IgxComboBas
         }
     }
 
+    /** Returns a string that should be populated in the combo's text box
+     * If the combo is remote, returns an empty string (as the items may not be loaded yet)
+     */
+    private concatTextValue(selection: any[]): string {
+        if (this.isRemote) { return ''; }
+        const value = this.displayKey !== null && this.displayKey !== undefined ?
+        this.convertKeysToItems(selection).map(entry => entry[this.displayKey]).join(', ') :
+        selection.join(', ');
+        return value;
+    }
+
     /** if there is a valueKey - map the keys to data items, else - just return the keys */
     private convertKeysToItems(keys: any[]) {
         if (this.comboAPI.valueKey === null) {