feat: add onChange event whenever a selection changes, fix #372 (#374)

* feat: add `onChange` event whenever a selection changes, fix #372

Author: ghiscoding

packages/demo/src/events/events.ts

@@ -45,6 +45,9 @@ export default class Example {
       onAfterCreate: () => {
         this.log('onAfterCreate event fire!\n');
       },
+      onChange: data => {
+        this.log(`onChange event fire! data: ${JSON.stringify(data)}\n`);
+      },
     }) as MultipleSelectInstance;
   }
 

packages/multiple-select-vanilla/src/MultipleSelectInstance.ts

@@ -2,9 +2,9 @@
  * @author zhixin wen <[email protected]>
  */
 import Constants from './constants.js';
-import type { HtmlStruct, OptGroupRowData, OptionDataObject, OptionRowData } from './models/interfaces.js';
+import type { HtmlStruct, OptGroupRowData, OptionRowData, OptionDataObject } from './models/interfaces.js';
 import type { MultipleSelectLocales } from './models/locale.interface.js';
-import type { CloseReason, MultipleSelectOption } from './models/multipleSelectOption.interface.js';
+import type { ClickedGroup, ClickedOption, CloseReason, MultipleSelectOption } from './models/multipleSelectOption.interface.js';
 import { BindingEventService } from './services/binding-event.service.js';
 import { VirtualScroll } from './services/virtual-scroll.js';
 import { compareObjects, deepCopy, findByParam, removeDiacritics, removeUndefined, setDataKeys, stripScripts } from './utils/utils.js';
@@ -787,10 +787,15 @@ export class MultipleSelectInstance {
     this.isPartiallyAllSelected = !this.isAllSelected && selectedTotal > 0;
 
     if (!ignoreTrigger) {
+      let eventCalled: 'onCheckAll' | 'onUncheckAll' | '' = '';
       if (this.isAllSelected) {
-        this.options.onCheckAll();
+        eventCalled = 'onCheckAll';
       } else if (selectedTotal === 0) {
-        this.options.onUncheckAll();
+        eventCalled = 'onUncheckAll';
+      }
+      if (eventCalled) {
+        this.options[eventCalled]();
+        this.handleOnChange(eventCalled);
       }
     }
   }
@@ -974,7 +979,7 @@ export class MultipleSelectInstance {
           this.options.onOptgroupClick(
             removeUndefined({
               label: group.label,
-              selected: group.selected,
+              selected: !!group.selected,
               data: group._data,
               children: group.children.map((child: any) => {
                 if (child) {
@@ -989,6 +994,11 @@ export class MultipleSelectInstance {
               }),
             }),
           );
+          this.handleOnChange('onOptgroupClick', {
+            label: group.label,
+            selected: !!group.selected,
+            type: group.type as 'optgroup',
+          });
         }) as EventListener,
         undefined,
         'group-checkbox-list',
@@ -1023,6 +1033,12 @@ export class MultipleSelectInstance {
               data: option._data,
             }),
           );
+          this.handleOnChange('onClick', {
+            label: option.text,
+            value: option.value,
+            selected: option.selected,
+            type: option.type as 'option',
+          });
 
           close();
         }) as EventListener,
@@ -1135,6 +1151,17 @@ export class MultipleSelectInstance {
     }
   }
 
+  protected handleOnChange(eventName: string, item?: ClickedGroup | ClickedOption) {
+    this.options.onChange({
+      eventName,
+      item,
+      selection: {
+        labels: this.getSelects('text'),
+        values: this.getSelects('value'),
+      },
+    });
+  }
+
   protected handleEscapeKey() {
     if (!this.options.keepOpen) {
       this.close('key.escape');
@@ -1456,7 +1483,7 @@ export class MultipleSelectInstance {
     let textSelects = this.getSelects('text');
 
     if (this.options.displayValues) {
-      textSelects = valueSelects;
+      textSelects = valueSelects as string[];
     }
 
     const spanElm = this.choiceElm?.querySelector<HTMLSpanElement>('span');
@@ -1508,7 +1535,7 @@ export class MultipleSelectInstance {
     // set selects to select
     const selectedValues = this.getSelects();
     if (this.options.single) {
-      this.elm.value = selectedValues.length ? selectedValues[0] : '';
+      this.elm.value = selectedValues.length ? (selectedValues[0] as string) : '';
     } else {
       // when multiple values could be set, we need to loop through each
       Array.from(this.elm.options).forEach(option => {
@@ -1616,8 +1643,8 @@ export class MultipleSelectInstance {
   }
 
   // value html, or text, default: 'value'
-  getSelects(type = 'value') {
-    const values = [];
+  getSelects<T extends 'text' | 'value'>(type: T = 'value' as T) {
+    const values: Array<string | number | boolean> = [];
     for (const row of this.data || []) {
       if ((row as OptGroupRowData).type === 'optgroup') {
         const selectedChildren = (row as OptGroupRowData).children.filter(child => child?.selected);
@@ -1640,10 +1667,10 @@ export class MultipleSelectInstance {
           values.push(value.join(''));
         }
       } else if (row.selected) {
-        values.push(type === 'value' ? row._value || (row as OptionRowData)[type] : (row as any)[type]);
+        values.push(type === 'value' ? row._value || (row as OptionRowData)[type] : (row as OptionRowData)[type]);
       }
     }
-    return values;
+    return values as T extends 'text' ? string[] : Array<string | number | boolean>;
   }
 
   setSelects(values: any[], type = 'value', ignoreTrigger = false) {

packages/multiple-select-vanilla/src/constants.ts

@@ -67,6 +67,7 @@ const DEFAULTS: Partial<MultipleSelectOption> = {
   labelTemplate: (elm: HTMLOptionElement) => elm.label,
 
   onBeforeOpen: noopFalse,
+  onChange: noopFalse,
   onOpen: noopFalse,
   onClose: noopFalse,
   onCheckAll: noopFalse,

packages/multiple-select-vanilla/src/models/multipleSelectOption.interface.ts

@@ -10,6 +10,18 @@ export interface MultipleSelectView {
   instance: any;
 }
 
+export interface ClickedItem<T extends 'option' | 'optgroup'> {
+  label: string;
+  selected: boolean;
+  type: T;
+}
+
+export interface ClickedGroup extends ClickedItem<'optgroup'> {}
+
+export interface ClickedOption extends ClickedItem<'option'> {
+  value?: any;
+}
+
 export type CloseReason =
   | 'body.click'
   | 'hover.mouseout'
@@ -291,7 +303,17 @@ export interface MultipleSelectOption extends MultipleSelectLocale {
   /** Bind an event handler to the “blur” */
   onBlur: () => void;
 
-  /** Fires when a an optgroup label is clicked on. */
+  /**
+   * Fires when any option/group selections changes.
+   * This event is triggered at the same time as these other events are triggered: (`onCheckAll`, `onUncheckAll`, `onClick`, `onOptgroupClick`)
+   */
+  onChange: (data: {
+    eventName: string;
+    item?: ClickedGroup | ClickedOption;
+    selection: { labels: string[]; values: Array<string | number | boolean> };
+  }) => void;
+
+  /** Fires when an optgroup label is clicked on. */
   onOptgroupClick: (view: MultipleSelectView) => void;
 
   /** Fires before a checkbox is clicked. Return `false` to prevent the click event. */

playwright/e2e/events.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '@playwright/test';
+import { expect, test } from '@playwright/test';
 
 test.describe('Events Demo', () => {
   test('executing multiple actions with ms-select should fire multiple events', async ({ page }) => {
@@ -40,6 +40,7 @@ test.describe('Events Demo', () => {
         'onBlur event fire!',
         'onOpen event fire!',
         'onOptgroupClick event fire! view: {"label":"Group 1","selected":true,"children":[null,{"text":"Option 1","value":"1","selected":true,"disabled":false},null,{"text":"Option 2","value":"2","selected":true,"disabled":false},null,{"text":"Option 3","value":"3","selected":true,"disabled":false},null]}',
+        'onChange event fire! data: {"eventName":"onOptgroupClick","item":{"label":"Group 1","selected":true,"type":"optgroup"},"selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]"],"values":["1","2","3"]}}',
       ].join('\n'),
     );
 
@@ -57,7 +58,9 @@ test.describe('Events Demo', () => {
         'onBlur event fire!',
         'onOpen event fire!',
         'onOptgroupClick event fire! view: {"label":"Group 1","selected":true,"children":[null,{"text":"Option 1","value":"1","selected":true,"disabled":false},null,{"text":"Option 2","value":"2","selected":true,"disabled":false},null,{"text":"Option 3","value":"3","selected":true,"disabled":false},null]}',
+        'onChange event fire! data: {"eventName":"onOptgroupClick","item":{"label":"Group 1","selected":true,"type":"optgroup"},"selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]"],"values":["1","2","3"]}}',
         'onCheckAll event fire!',
+        'onChange event fire! data: {"eventName":"onCheckAll","selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]","[Group 2: Option 4, Option 5, Option 6]","[Group 3: Option 7, Option 8, Option 9]"],"values":["1","2","3","4","5","6","7","8","9"]}}',
       ].join('\n'),
     );
 
@@ -75,8 +78,11 @@ test.describe('Events Demo', () => {
         'onBlur event fire!',
         'onOpen event fire!',
         'onOptgroupClick event fire! view: {"label":"Group 1","selected":true,"children":[null,{"text":"Option 1","value":"1","selected":true,"disabled":false},null,{"text":"Option 2","value":"2","selected":true,"disabled":false},null,{"text":"Option 3","value":"3","selected":true,"disabled":false},null]}',
+        'onChange event fire! data: {"eventName":"onOptgroupClick","item":{"label":"Group 1","selected":true,"type":"optgroup"},"selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]"],"values":["1","2","3"]}}',
         'onCheckAll event fire!',
+        'onChange event fire! data: {"eventName":"onCheckAll","selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]","[Group 2: Option 4, Option 5, Option 6]","[Group 3: Option 7, Option 8, Option 9]"],"values":["1","2","3","4","5","6","7","8","9"]}}',
         'onCheckAll event fire!',
+        'onChange event fire! data: {"eventName":"onCheckAll","selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]","[Group 2: Option 4, Option 5, Option 6]","[Group 3: Option 7, Option 8, Option 9]"],"values":["1","2","3","4","5","6","7","8","9"]}}',
         'onFilter event fire! text: 1',
       ].join('\n'),
     );
@@ -95,10 +101,14 @@ test.describe('Events Demo', () => {
         'onBlur event fire!',
         'onOpen event fire!',
         'onOptgroupClick event fire! view: {"label":"Group 1","selected":true,"children":[null,{"text":"Option 1","value":"1","selected":true,"disabled":false},null,{"text":"Option 2","value":"2","selected":true,"disabled":false},null,{"text":"Option 3","value":"3","selected":true,"disabled":false},null]}',
+        'onChange event fire! data: {"eventName":"onOptgroupClick","item":{"label":"Group 1","selected":true,"type":"optgroup"},"selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]"],"values":["1","2","3"]}}',
         'onCheckAll event fire!',
+        'onChange event fire! data: {"eventName":"onCheckAll","selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]","[Group 2: Option 4, Option 5, Option 6]","[Group 3: Option 7, Option 8, Option 9]"],"values":["1","2","3","4","5","6","7","8","9"]}}',
         'onCheckAll event fire!',
+        'onChange event fire! data: {"eventName":"onCheckAll","selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]","[Group 2: Option 4, Option 5, Option 6]","[Group 3: Option 7, Option 8, Option 9]"],"values":["1","2","3","4","5","6","7","8","9"]}}',
         'onFilter event fire! text: 1',
         'onCheckAll event fire!',
+        'onChange event fire! data: {"eventName":"onCheckAll","selection":{"labels":["[Group 1: Option 1, Option 2, Option 3]","[Group 2: Option 4, Option 5, Option 6]","[Group 3: Option 7, Option 8, Option 9]"],"values":["1","2","3","4","5","6","7","8","9"]}}',
         'onFilter event fire! text: ',
         'onFilterClear event fire!',
       ].join('\n'),