feat(Combobox): allow custom value (#14935)

* feat(Combobox): add allowCustomValue prop

* test(Combobox): add tests to cover new functionality

* docs(Combobox): add some docs around the new  prop

* docs(Combobox): add test story

* test(snapshot): update snapshots

* chore(storybook): remove commented out code

---------

Co-authored-by: Taylor Jones <tay1orjones@users.noreply.github.com>

Author: tw15egan

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -1054,6 +1054,9 @@ Map {
   "ComboBox" => Object {
     "$$typeof": Symbol(react.forward_ref),
     "propTypes": Object {
+      "allowCustomValue": Object {
+        "type": "bool",
+      },
       "aria-label": Object {
         "type": "string",
       },

packages/react/src/components/ComboBox/ComboBox-test.js

@@ -101,6 +101,21 @@ describe('ComboBox', () => {
     });
   });
 
+  it('should retain value if custom value is entered and `allowCustomValue` is set', async () => {
+    render(<ComboBox {...mockProps} allowCustomValue />);
+
+    expect(findInputNode()).toHaveDisplayValue('');
+
+    await userEvent.type(findInputNode(), 'Apple');
+    // Should close menu and keep value in input, even though it is not in the item list
+    await userEvent.keyboard('[Enter]');
+    assertMenuClosed();
+    expect(findInputNode()).toHaveDisplayValue('Apple');
+    // Should retain value on blur
+    await userEvent.keyboard('[Tab]');
+    expect(findInputNode()).toHaveDisplayValue('Apple');
+  });
+
   describe('should display initially selected item found in `initialSelectedItem`', () => {
     it('using an object type for the `initialSelectedItem` prop', () => {
       render(

packages/react/src/components/ComboBox/ComboBox.mdx

@@ -21,6 +21,7 @@ import ComboBox from '../ComboBox';
 - [itemToElement](#itemtoelement)
 - [itemToString](#itemtostring)
 - [shouldFilterItem](#shouldfilteritem)
+- [allowCustomValue](#allowcustomvalue)
 - [With Layer](#with-layer)
 - [Feedback](#feedback)
 
@@ -147,6 +148,19 @@ const filterItems = (menu) => {
 />;
 ```
 
+## `allowCustomValue`
+
+By default, if text is entered into the `Combobox` and it does not match an
+item, it will be cleared on blur. However, you can change this behavior by
+passing in the `allowCustomValue` prop. This will allow a user to close the menu
+and accept a custom value by pressing `Enter` as well as retain the value on
+blur. The `inputValue` is provided as a second argument to the `onChange`
+callback.
+
+```js
+{selectedItem: undefined, inputValue: 'Apple'}
+```
+
 ## With Layer
 
 <Canvas>

packages/react/src/components/ComboBox/ComboBox.stories.js

@@ -79,6 +79,32 @@ export const Default = () => (
   </div>
 );
 
+export const AllowCustomValue = () => {
+  const filterItems = (menu) => {
+    return menu?.item?.toLowerCase().includes(menu?.inputValue?.toLowerCase());
+  };
+  return (
+    <div style={{ width: 300 }}>
+      <ComboBox
+        allowCustomValue
+        shouldFilterItem={filterItems}
+        onChange={(e) => {
+          console.log(e);
+        }}
+        id="carbon-combobox"
+        items={['Apple', 'Orange', 'Banana', 'Pineapple', 'Raspberry', 'Lime']}
+        downshiftProps={{
+          onStateChange: () => {
+            console.log('the state has changed');
+          },
+        }}
+        titleText="ComboBox title"
+        helperText="Combobox helper text"
+      />
+    </div>
+  );
+};
+
 export const _WithLayer = () => (
   <WithLayer>
     {(layer) => (

packages/react/src/components/ComboBox/ComboBox.tsx

@@ -55,6 +55,7 @@ const {
   clickButton,
   blurButton,
   changeInput,
+  blurInput,
 } = Downshift.stateChangeTypes;
 
 const defaultItemToString = <ItemType,>(item: ItemType | null) => {
@@ -127,13 +128,20 @@ const getInstanceId = setupGetInstanceId();
 type ExcludedAttributes = 'id' | 'onChange' | 'onClick' | 'type' | 'size';
 
 interface OnChangeData<ItemType> {
-  selectedItem: ItemType | null;
+  selectedItem: ItemType | null | undefined;
+  inputValue?: string | null;
 }
 
 type ItemToStringHandler<ItemType> = (item: ItemType | null) => string;
 
 export interface ComboBoxProps<ItemType>
   extends Omit<InputHTMLAttributes<HTMLInputElement>, ExcludedAttributes> {
+  /**
+   * Specify whether or not the ComboBox should allow a value that is
+   * not in the list to be entered in the input
+   */
+  allowCustomValue?: boolean;
+
   /**
    * Specify a label to be read by screen readers on the container node
    * 'aria-label' of the ListBox component.
@@ -329,6 +337,7 @@ const ComboBox = forwardRef(
       translateWithId,
       warn,
       warnText,
+      allowCustomValue = false,
       ...rest
     } = props;
     const prefix = usePrefix();
@@ -447,6 +456,14 @@ const ComboBox = forwardRef(
         case changeInput:
           updateHighlightedIndex(getHighlightedIndex(changes));
           break;
+        case blurInput:
+          if (allowCustomValue) {
+            setInputValue(inputValue);
+            if (onChange) {
+              onChange({ selectedItem, inputValue });
+            }
+          }
+          break;
       }
     };
 
@@ -571,8 +588,18 @@ const ComboBox = forwardRef(
                 event.stopPropagation();
               }
 
-              if (match(event, keys.Enter) && !inputValue) {
+              if (
+                match(event, keys.Enter) &&
+                (!inputValue || allowCustomValue)
+              ) {
                 toggleMenu();
+
+                // Since `onChange` does not normally fire when the menu is closed, we should
+                // manually fire it when `allowCustomValue` is provided, the menu is closing,
+                // and there is a value.
+                if (allowCustomValue && isOpen && inputValue) {
+                  onChange({ selectedItem, inputValue });
+                }
               }
 
               if (match(event, keys.Escape) && inputValue) {
@@ -744,6 +771,12 @@ const ComboBox = forwardRef(
 
 ComboBox.displayName = 'ComboBox';
 ComboBox.propTypes = {
+  /**
+   * Specify whether or not the ComboBox should allow a value that is
+   * not in the list to be entered in the input
+   */
+  allowCustomValue: PropTypes.bool,
+
   /**
    * 'aria-label' of the ListBox component.
    * Specify a label to be read by screen readers on the container node