[EuiSelectableTemplateSitewide] Pass keyboard/mouse event to onChange handler (#5926)

* Enhance EuiSelectable to send back click/keyboard events

- which will allow consumers to, e.g. react to shift clicks

* [REVERT ME] Example of how Kibana would update their `onChange` event to react to shift key

* changelog

* Revert "[REVERT ME] Example of how Kibana would update their `onChange` event to react to shift key"

This reverts commit 1d893f4.

Author: Constance

src/components/selectable/selectable.test.tsx

@@ -226,12 +226,8 @@ describe('EuiSelectable', () => {
         },
       ];
 
-      const onChange = (options: OptionalOption[]) => {
-        jest.fn(() => options);
-      };
-
       const component = mount(
-        <EuiSelectable<OptionalOption> options={options} onChange={onChange}>
+        <EuiSelectable<OptionalOption> options={options}>
           {(list) => list}
         </EuiSelectable>
       );
@@ -260,12 +256,8 @@ describe('EuiSelectable', () => {
         },
       ];
 
-      const onChange = (options: ExtendedOption[]) => {
-        jest.fn(() => options);
-      };
-
       const component = mount(
-        <EuiSelectable<ExtendedOption> options={options} onChange={onChange}>
+        <EuiSelectable<ExtendedOption> options={options}>
           {(list) => list}
         </EuiSelectable>
       );
@@ -321,6 +313,27 @@ describe('EuiSelectable', () => {
     });
   });
 
+  describe('onChange', () => {
+    it('calls onChange with selected options array and click/keyboard event', () => {
+      const onChange = jest.fn();
+      const component = mount(
+        <EuiSelectable options={options} onChange={onChange}>
+          {(list) => list}
+        </EuiSelectable>
+      );
+
+      component.find('[role="option"]').first().simulate('click');
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange.mock.calls[0][0][0].checked).toEqual('on');
+      expect(onChange.mock.calls[0][1].type).toEqual('click');
+
+      component.simulate('keydown', { key: 'Enter', shiftKey: true });
+      expect(onChange).toHaveBeenCalledTimes(2);
+      expect(onChange.mock.calls[1][0][0].checked).toEqual('on');
+      expect(onChange.mock.calls[1][1].type).toEqual('keydown');
+    });
+  });
+
   describe('errorMessage prop', () => {
     it('does not render the message when not defined', () => {
       const component = render(

src/components/selectable/selectable.tsx

@@ -13,6 +13,7 @@ import React, {
   createRef,
   ReactElement,
   KeyboardEvent,
+  MouseEvent,
 } from 'react';
 import classNames from 'classnames';
 import { CommonProps, ExclusiveUnion } from '../common';
@@ -33,6 +34,8 @@ import { EuiSelectableOptionsListProps } from './selectable_list/selectable_list
 import { EuiSelectableSearchProps } from './selectable_search/selectable_search';
 import { Align } from 'react-window';
 
+export type EuiSelectableOnChangeEvent = KeyboardEvent | MouseEvent;
+
 type RequiredEuiSelectableOptionsListProps = Omit<
   EuiSelectableOptionsListProps,
   keyof typeof EuiSelectableList['defaultProps']
@@ -92,9 +95,13 @@ export type EuiSelectableProps<T = {}> = CommonProps &
      */
     options: Array<EuiSelectableOption<T>>;
     /**
-     * Passes back the altered `options` array with selected options as
+     * Passes back the altered `options` array with selected options having `checked: 'on'`.
+     * Also passes back the React click/keyboard event as a second argument.
      */
-    onChange?: (options: Array<EuiSelectableOption<T>>) => void;
+    onChange?: (
+      options: Array<EuiSelectableOption<T>>,
+      event: EuiSelectableOnChangeEvent
+    ) => void;
     /**
      * Sets the single selection policy of
      * `false`: allows multiple selection
@@ -334,7 +341,8 @@ export class EuiSelectable<T = {}> extends Component<
         event.stopPropagation();
         if (this.state.activeOptionIndex != null && optionsList) {
           optionsList.onAddOrRemoveOption(
-            this.state.visibleOptions[this.state.activeOptionIndex]
+            this.state.visibleOptions[this.state.activeOptionIndex],
+            event
           );
         }
         break;
@@ -428,7 +436,10 @@ export class EuiSelectable<T = {}> extends Component<
     });
   };
 
-  onOptionClick = (options: Array<EuiSelectableOption<T>>) => {
+  onOptionClick = (
+    options: Array<EuiSelectableOption<T>>,
+    event: EuiSelectableOnChangeEvent
+  ) => {
     const { isPreFiltered, onChange } = this.props;
     const { searchValue } = this.state;
     const visibleOptions = getMatchingOptions(
@@ -440,7 +451,7 @@ export class EuiSelectable<T = {}> extends Component<
     this.setState({ visibleOptions });
 
     if (onChange) {
-      onChange(options);
+      onChange(options, event);
     }
   };
 

src/components/selectable/selectable_list/selectable_list.tsx

@@ -24,6 +24,7 @@ import { CommonProps, ExclusiveUnion } from '../../common';
 import { EuiAutoSizer } from '../../auto_sizer';
 import { EuiHighlight } from '../../highlight';
 import { EuiSelectableOption } from '../selectable_option';
+import { EuiSelectableOnChangeEvent } from '../selectable';
 import {
   EuiSelectableListItem,
   EuiSelectableListItemProps,
@@ -109,7 +110,10 @@ export type EuiSelectableListProps<T> = EuiSelectableOptionsListProps & {
   /**
    * Returns the array of options with altered checked state
    */
-  onOptionClick: (options: Array<EuiSelectableOption<T>>) => void;
+  onOptionClick: (
+    options: Array<EuiSelectableOption<T>>,
+    event: EuiSelectableOnChangeEvent
+  ) => void;
   /**
    * Custom render for the label portion of the option;
    * Takes (option, searchValue), returns ReactNode
@@ -273,7 +277,9 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
         onMouseDown={() => {
           setActiveOptionIndex(index);
         }}
-        onClick={() => this.onAddOrRemoveOption(option)}
+        onClick={(event) => {
+          this.onAddOrRemoveOption(option, event);
+        }}
         ref={ref ? ref.bind(null, index) : undefined}
         isFocused={activeOptionIndex === index}
         title={searchableLabel || label}
@@ -414,7 +420,10 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
     );
   }
 
-  onAddOrRemoveOption = (option: EuiSelectableOption<T>) => {
+  onAddOrRemoveOption = (
+    option: EuiSelectableOption<T>,
+    event: EuiSelectableOnChangeEvent
+  ) => {
     if (option.disabled) {
       return;
     }
@@ -425,17 +434,20 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
       visibleOptions.findIndex(({ label }) => label === option.label),
       () => {
         if (option.checked === 'on' && allowExclusions) {
-          this.onExcludeOption(option);
+          this.onExcludeOption(option, event);
         } else if (option.checked === 'on' || option.checked === 'off') {
-          this.onRemoveOption(option);
+          this.onRemoveOption(option, event);
         } else {
-          this.onAddOption(option);
+          this.onAddOption(option, event);
         }
       }
     );
   };
 
-  private onAddOption = (addedOption: EuiSelectableOption<T>) => {
+  private onAddOption = (
+    addedOption: EuiSelectableOption<T>,
+    event: EuiSelectableOnChangeEvent
+  ) => {
     const { onOptionClick, options, singleSelection } = this.props;
 
     const updatedOptions = options.map((option) => {
@@ -453,10 +465,13 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
       return updatedOption;
     });
 
-    onOptionClick(updatedOptions);
+    onOptionClick(updatedOptions, event);
   };
 
-  private onRemoveOption = (removedOption: EuiSelectableOption<T>) => {
+  private onRemoveOption = (
+    removedOption: EuiSelectableOption<T>,
+    event: EuiSelectableOnChangeEvent
+  ) => {
     const { onOptionClick, singleSelection, options } = this.props;
 
     const updatedOptions = options.map((option) => {
@@ -469,10 +484,13 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
       return updatedOption;
     });
 
-    onOptionClick(updatedOptions);
+    onOptionClick(updatedOptions, event);
   };
 
-  private onExcludeOption = (excludedOption: EuiSelectableOption<T>) => {
+  private onExcludeOption = (
+    excludedOption: EuiSelectableOption<T>,
+    event: EuiSelectableOnChangeEvent
+  ) => {
     const { onOptionClick, options } = this.props;
     excludedOption.checked = 'off';
 
@@ -486,6 +504,6 @@ export class EuiSelectableList<T> extends Component<EuiSelectableListProps<T>> {
       return updatedOption;
     });
 
-    onOptionClick(updatedOptions);
+    onOptionClick(updatedOptions, event);
   };
 }

upcoming_changelogs/5926.md

@@ -0,0 +1 @@
+- Added the click/keydown event as an argument to `EuiSelectable`/`EuiSelectableTemplateSitewide`'s `onChange` prop