fix(combos): selection event consistent data items, value args (#13619)

Rename existing `newSelection` and `oldSelection` to `newValue` and
`oldValue` respectively. Add new args in their place that emit data
items consistently regardless of `valueKey`. For `IgxCombo` also
update `added` and `removed` collections to always contain data items

Author: wnvko

CHANGELOG.md

@@ -17,7 +17,17 @@ All notable changes for each version of this project will be documented in this
 - We're working on reducing the library size
     - IgxRadioComponent has been reduced in half
     - IgxSwitchComponent has been reduced in half
+- `IgxCombo`
+    - **Breaking Change** `IComboSelectionChangingEventArgs` properties `newSelection` and `oldSelection` have been renamed to `newValue` and `oldValue` respectively to better reflect their function. Just like Combo's `value`, those will emit either the specified property values or full data items depending on whether `valueKey` is set or not. Automatic migrations are available and will be applied on `ng update`.
+    - `IComboSelectionChangingEventArgs` exposes two new properties `newSelection` and `oldSelection` in place of the old ones that are no longer affected by `valueKey` and consistently emit items from Combo's `data`.
+      
+      Note: In remote data scenarios with `valueKey` set, selected items that are not currently part of the loaded data chunk will be emitted a partial item data object with the `valueKey` property.
+    - **Breaking Change** - `IComboSelectionChangingEventArgs` properties `added` and `removed` now always contain data items, regardless of `valueKey` being set. This aligns them with the updated `newSelection` and `oldSelection` properties, including the same limitation for remote data as described above.
+- `IgxSimpleCombo`
+    - **Breaking Change** - `ISimpleComboSelectionChangingEventArgs` properties `newSelection` and `oldSelection` have been renamed to `newValue` and `oldValue` respectively to better reflect their function. Just like Combo's `value`, those will emit either the specified property value or full data item depending on whether `valueKey` is set or not. Automatic migrations are available and will be applied on `ng update`.
+    - `ISimpleComboSelectionChangingEventArgs` exposes two new properties `newSelection` and `oldSelection` in place of the old ones that are no longer affected by `valueKey` and consistently emit items from Combo's `data`.
 
+      Note: In remote data scenarios with `valueKey` set, selected items that are not currently part of the loaded data chunk will be emitted a partial item data object with the `valueKey` property.
 ## 16.1.4
 ### New Features
 - `Themes`:

projects/igniteui-angular/migrations/update-17_0_0/changes/members.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "../../common/schema/members-changes.schema.json",
+    "changes": [
+        {
+            "member": "newSelection",
+            "replaceWith": "newValue",
+            "definedIn": [
+                "IComboSelectionChangingEventArgs",
+                "ISimpleComboSelectionChangingEventArgs"
+            ]
+        },
+        {
+            "member": "oldSelection",
+            "replaceWith": "oldValue",
+            "definedIn": [
+                "IComboSelectionChangingEventArgs",
+                "ISimpleComboSelectionChangingEventArgs"
+            ]
+        }
+    ]
+}

projects/igniteui-angular/migrations/update-17_0_0/index.spec.ts

@@ -206,6 +206,66 @@ describe(`Update to ${version}`, () => {
         );
     });
 
+    it('Should properly rename newSelection and oldSelection property to newValue and oldValue in Combo', async () => {
+        pending('set up tests for migrations through lang service');
+        appTree.create('/testSrc/appPrefix/component/test.component.ts',
+        `
+        import { IgxComboComponent, IComboSelectionChangingEventArgs } from 'igniteui-angular';
+        export class MyClass {
+            public handleSelectionChanging(e: IComboSelectionChangingEventArgs) {
+                const newSelection = e.newSelection;
+                const oldSelection = e.oldSelection;
+            }
+        }
+        `);
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(
+            tree.readContent('/testSrc/appPrefix/component/test.component.ts')
+        ).toEqual(
+        `
+        import { IgxComboComponent, IComboSelectionChangingEventArgs } from 'igniteui-angular';
+        export class MyClass {
+            public handleSelectionChanging(e: IComboSelectionChangingEventArgs) {
+                const newSelection = e.newValue;
+                const oldSelection = e.oldValue;
+            }
+        }
+        `
+        );
+    });
+
+    it('Should properly rename newSelection and oldSelection property to newValue and oldValue SimpleCombo', async () => {
+        pending('set up tests for migrations through lang service');
+        appTree.create('/testSrc/appPrefix/component/test.component.ts',
+        `
+        import { IgxSimpleComboComponent, ISimpleComboSelectionChangingEventArgs } from 'igniteui-angular';
+        export class MyClass {
+            public handleSelectionChanging(e: ISimpleComboSelectionChangingEventArgs) {
+                const newSelection = e.newSelection;
+                const oldSelection = e.oldSelection;
+            }
+        }
+        `);
+
+        const tree = await schematicRunner.runSchematic(migrationName, {}, appTree);
+
+        expect(
+            tree.readContent('/testSrc/appPrefix/component/test.component.ts')
+        ).toEqual(
+        `
+        import { IgxComboComponent, IComboSelectionChangingEventArgs } from 'igniteui-angular';
+        export class MyClass {
+            public handleSelectionChanging(e: IComboSelectionChangingEventArgs) {
+                const newSelection = e.newValue;
+                const oldSelection = e.oldValue;
+            }
+        }
+        `
+        );
+    });
+
     for (const igPackage of ['igniteui-angular', '@infragistics/igniteui-angular']) {
         it('should move animation imports from igniteui-angular to igniteui-angular/animations', async () => {
             appTree.create(`/testSrc/appPrefix/component/test.component.ts`,

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

@@ -1295,11 +1295,13 @@ export abstract class IgxComboBaseDirective extends DisplayDensityBase implement
             return keys;
         }
 
-        // map keys vs. filter data to retain the order of the selected items
-        return keys.map(key => isNaNvalue(key)
-            ? this.data.find(entry => isNaNvalue(entry[this.valueKey]))
-            : this.data.find(entry => entry[this.valueKey] === key))
-            .filter(e => e !== undefined);
+        return keys.map(key => {
+            const item = isNaNvalue(key)
+                ? this.data.find(entry => isNaNvalue(entry[this.valueKey]))
+                : this.data.find(entry => entry[this.valueKey] === key);
+
+            return item !== undefined ? item : { [this.valueKey]: key };
+        });
     }
 
     protected checkMatch(): void {