LG-3959 Combobox value change

.changeset/ten-pandas-play.md

@@ -0,0 +1,25 @@
+---
+'@leafygreen-ui/combobox': minor
+---
+
+Combobox `onChange` callback now receives a 2nd argument. Use this argument to determine what value was inserted or deleted from a multiselect value.
+[JIRA Ticket](https://jira.mongodb.org/browse/LG-3959)
+
+Example:
+```tsx
+<Combobox 
+  multiselect
+  value={['apple', 'banana']}
+  onChange={(val, diff) => {
+    console.log(value) // ['apple']
+    console.log(diff); // { diffType: 'delete', value: 'banana' }
+  }} 
+/>
+```
+
+```ts
+interface DiffObject {
+  diffType: 'insert' | 'delete';
+  value: string | Array<string>;
+}
+```

packages/combobox/src/Combobox/Combobox.spec.tsx

@@ -541,6 +541,31 @@ describe('packages/combobox', () => {
         }
       });
 
+      test('Clicking an option fires onChange', () => {
+        const onChange = jest.fn();
+        const { openMenu } = renderCombobox(select, {
+          onChange,
+        });
+        const { optionElements } = openMenu();
+        expect(optionElements).not.toBeUndefined();
+        const option3 = (optionElements as HTMLCollectionOf<HTMLLIElement>)[2];
+        act(() => {
+          userEvent.click(option3);
+        });
+
+        if (select === 'multiple') {
+          expect(onChange).toHaveBeenCalledWith(
+            expect.arrayContaining(['carrot']),
+            expect.objectContaining({
+              diffType: 'insert',
+              value: 'carrot',
+            }),
+          );
+        } else {
+          expect(onChange).toHaveBeenCalledWith('carrot');
+        }
+      });
+
       testSingleSelect('Clicking selected option closes menu', async () => {
         const { openMenu } = renderCombobox(select, {
           initialValue: 'apple',
@@ -749,6 +774,32 @@ describe('packages/combobox', () => {
           });
         });
 
+        testMultiSelect(
+          'Clicking chip X button fires onChange with diff',
+          async () => {
+            const onChange = jest.fn();
+            const initialValue = ['apple', 'banana', 'carrot'];
+            const { queryChipsByName } = renderCombobox(select, {
+              onChange,
+              initialValue,
+            });
+            const appleChip = queryChipsByName('Apple');
+            expect(appleChip).not.toBeNull();
+            const appleChipButton = appleChip!.querySelector('button')!;
+            userEvent.click(appleChipButton);
+            await waitFor(() => {
+              expect(appleChip).not.toBeInTheDocument();
+              expect(onChange).toHaveBeenCalledWith(
+                expect.arrayContaining(['banana', 'carrot']),
+                expect.objectContaining({
+                  diffType: 'delete',
+                  value: 'apple',
+                }),
+              );
+            });
+          },
+        );
+
         testMultiSelect('Clicking chip text focuses the chip', () => {
           const initialValue = ['apple', 'banana', 'carrot'];
           const { queryChipsByName, queryAllChips } = renderCombobox(select, {
@@ -842,9 +893,18 @@ describe('packages/combobox', () => {
           const { inputEl, openMenu } = renderCombobox(select, { onChange });
           openMenu();
           userEvent.type(inputEl!, '{arrowdown}{enter}');
-          expect(onChange).toHaveBeenCalledWith(
-            select === 'single' ? 'banana' : ['banana'],
-          );
+
+          if (select === 'multiple') {
+            expect(onChange).toHaveBeenCalledWith(
+              ['banana'],
+              expect.objectContaining({
+                diffType: 'insert',
+                value: 'banana',
+              }),
+            );
+          } else {
+            expect(onChange).toHaveBeenCalledWith('banana');
+          }
         });
 
         test('does not fire onClear handler', () => {
@@ -1359,7 +1419,8 @@ describe('packages/combobox', () => {
      */
     describe('onClear', () => {
       test('Clear button calls onClear callback', () => {
-        const initialValue = select === 'multiple' ? ['apple'] : 'apple';
+        const initialValue =
+          select === 'multiple' ? ['apple', 'banana'] : 'apple';
         const onClear = jest.fn();
         const { clearButtonEl } = renderCombobox(select, {
           initialValue,
@@ -1370,7 +1431,8 @@ describe('packages/combobox', () => {
       });
 
       test('Clear button does not force the menu to reopen', () => {
-        const initialValue = select === 'multiple' ? ['apple'] : 'apple';
+        const initialValue =
+          select === 'multiple' ? ['apple', 'banana'] : 'apple';
         const onClear = jest.fn();
         const { clearButtonEl, queryByRole } = renderCombobox(select, {
           initialValue,
@@ -1381,8 +1443,9 @@ describe('packages/combobox', () => {
         expect(queryByRole('listbox')).not.toBeInTheDocument();
       });
 
-      test('Clear button clears the value of the input', () => {
-        const initialValue = select === 'multiple' ? ['apple'] : 'apple';
+      test('Clear button clears the value of the input', async () => {
+        const initialValue =
+          select === 'multiple' ? ['apple', 'banana'] : 'apple';
         const { inputEl, clearButtonEl, queryChipsByName } = renderCombobox(
           select,
           {
@@ -1396,10 +1459,34 @@ describe('packages/combobox', () => {
           expect(inputEl).toHaveValue('Apple');
         }
 
-        act(() => {
-          userEvent.click(clearButtonEl!);
+        userEvent.click(clearButtonEl!);
+        await waitFor(() => {
+          expect(inputEl).toHaveValue('');
         });
-        expect(inputEl).toHaveValue('');
+      });
+
+      test('Clear button calls onChange callback', () => {
+        const onChange = jest.fn();
+        const initialValue =
+          select === 'multiple' ? ['apple', 'banana'] : 'apple';
+        const { clearButtonEl } = renderCombobox(select, {
+          initialValue,
+          onChange,
+        });
+
+        userEvent.click(clearButtonEl!);
+
+        if (select === 'multiple') {
+          expect(onChange).toHaveBeenCalledWith(
+            [],
+            expect.objectContaining({
+              diffType: 'delete',
+              value: ['apple', 'banana'],
+            }),
+          );
+        } else {
+          expect(onChange).toHaveBeenCalledWith(null);
+        }
       });
 
       test('Focus returns to input element after clear button is clicked', async () => {

packages/combobox/src/Combobox/Combobox.tsx

@@ -45,6 +45,7 @@ import { InternalComboboxOption } from '../ComboboxOption';
 import {
   ComboboxElement,
   ComboboxSize,
+  DiffObject,
   getNullSelection,
   onChangeType,
   Overflow,
@@ -62,6 +63,7 @@ import {
   getValueForDisplayName,
 } from '../utils';
 
+import { isValueCurrentSelection } from './utils/isValueCurrentSelection';
 import {
   baseComboboxStyles,
   baseInputElementStyle,
@@ -224,6 +226,11 @@ export function Combobox<M extends boolean>({
       if (isMultiselect(selection)) {
         // We know M is true here
         const newSelection: SelectValueType<true> = clone(selection);
+        const multiselectOnChange = onChange as onChangeType<true>;
+        const diff: DiffObject = {
+          diffType: 'delete',
+          value: value ?? selection,
+        };
 
         if (isNull(value)) {
           newSelection.length = 0;
@@ -234,38 +241,23 @@ export function Combobox<M extends boolean>({
           } else {
             // add to array
             newSelection.push(value);
+            diff.diffType = 'insert';
             // clear text
             setInputValue('');
           }
         }
         setSelection(newSelection as SelectValueType<M>);
-        (onChange as onChangeType<true>)?.(
-          newSelection as SelectValueType<true>,
-        );
+        multiselectOnChange?.(newSelection, diff);
       } else {
-        const newSelection: SelectValueType<M> = value as SelectValueType<M>;
-        setSelection(newSelection);
-        (onChange as onChangeType<false>)?.(
-          newSelection as SelectValueType<false>,
-        );
+        const newSelection: SelectValueType<false> = value;
+        const singleSelectOnChange = onChange as onChangeType<false>;
+        setSelection(newSelection as SelectValueType<M>);
+        singleSelectOnChange?.(newSelection);
       }
     },
     [isMultiselect, onChange, selection],
   );
 
-  /**
-   * Returns whether a given value is included in, or equal to, the current selection
-   * @param value the option value to check
-   */
-  const isValueCurrentSelection = useCallback(
-    (value: string): boolean => {
-      return isMultiselect(selection)
-        ? selection.includes(value)
-        : value === selection;
-    },
-    [isMultiselect, selection],
-  );
-
   /**
    * Returns whether given text is included in, or equal to, the current selection.
    * Similar to `isValueCurrentSelection`, but assumes the text argument is the `displayName` for the selection
@@ -274,9 +266,9 @@ export function Combobox<M extends boolean>({
   const isTextCurrentSelection = useCallback(
     (text: string): boolean => {
       const value = getValueForDisplayName(text, allOptions);
-      return isValueCurrentSelection(value);
+      return isValueCurrentSelection(value, selection);
     },
-    [allOptions, isValueCurrentSelection],
+    [allOptions, selection],
   );
 
   /**
@@ -841,6 +833,7 @@ export function Combobox<M extends boolean>({
   }, []);
 
   // When controlled value changes, update the selection
+  // TODO: use useControlledValue
   useEffect(() => {
     if (!isUndefined(value) && value !== prevValue) {
       if (isNull(value)) {

packages/combobox/src/Combobox/utils/isValueCurrentSelection.ts

@@ -0,0 +1,14 @@
+import { SelectValueType } from '../../types';
+
+/**
+ * Returns whether a given value is included in, or equal to, the current selection
+ * @param value the option value to check
+ */
+export const isValueCurrentSelection = (
+  value: string,
+  selection: SelectValueType<boolean> | null,
+): boolean => {
+  return Array.isArray(selection)
+    ? selection.includes(value)
+    : value === selection;
+};

packages/combobox/src/types/Combobox.types.ts

@@ -68,14 +68,20 @@ export type SelectValueType<M extends boolean> = M extends true
   ? Array<string>
   : string | null;
 
+/** Represents an element that was added or removed from the multiselect value array */
+export interface DiffObject {
+  diffType: 'insert' | 'delete';
+  value: string | Array<string>;
+}
+
 /**
  * Callback event fired when the value changes
  *
  * Type varies depending on the value of `multiselect`
  */
 // TODO: onChange signature should match the native event handler signature
 export type onChangeType<M extends boolean> = M extends true
-  ? (value: SelectValueType<true>) => void
+  ? (value: SelectValueType<true>, diff?: DiffObject) => void
   : (value: SelectValueType<false>) => void;
 
 /**

packages/combobox/src/types/index.ts

@@ -1,6 +1,7 @@
 export {
   ComboboxElement,
   ComboboxSize,
+  DiffObject,
   getNullSelection,
   onChangeType,
   Overflow,