feat(Combobox): add custom formValue prop to ComboboxOption

docs/pages/components/Combobox.mdx

@@ -213,6 +213,38 @@ function ComboboxControlledExample() {
 }
 ```
 
+## Form Values
+
+By default when `name` is set, the value submitted via form submissions for the given field name will be the `value` of the combobox input field or the inner text contents of the combobox option when `value` is omitted.
+
+```jsx example
+<FieldWrap>
+  <Combobox name="fruit" label="Fruit" defaultValue="Peach">
+    <ComboboxOption value="Apple">🍎 Apple</ComboboxOption>
+    <ComboboxOption value="Banana">🍌 Banana</ComboboxOption>
+    <ComboboxOption value="Cucumber">🥒 Cucumber</ComboboxOption>
+    <ComboboxOption value="Orange">🍊 Orange</ComboboxOption>
+    <ComboboxOption value="Peach">🍑 Peach</ComboboxOption>
+    <ComboboxOption value="Pear">🍐 Pear</ComboboxOption>
+  </Combobox>
+</FieldWrap>
+```
+
+Alternatively, a custom `formValue` prop can be set for each combobox option to provide an opaque form value for form submissions, while still allowing for a different input value for the combobox input field.
+
+```jsx example
+<FieldWrap>
+  <Combobox name="fruit" label="Fruit" defaultValue="Peach">
+    <ComboboxOption value="Apple" formValue="1">🍎 Apple</ComboboxOption>
+    <ComboboxOption value="Banana" formValue="2">🍌 Banana</ComboboxOption>
+    <ComboboxOption value="Cucumber" formValue="3">🥒 Cucumber</ComboboxOption>
+    <ComboboxOption value="Orange" formValue="4">🍊 Orange</ComboboxOption>
+    <ComboboxOption value="Peach" formValue="5">🍑 Peach</ComboboxOption>
+    <ComboboxOption value="Pear" formValue="6">🍐 Pear</ComboboxOption>
+  </Combobox>
+</FieldWrap>
+```
+
 ## Autocomplete
 
 There are a couple of different methods to control the auto completion of the options in the listbox. By default, autocomplete is set to "manual" meaning selections will be filtered based on the value of the input, and a value will need to be manually selected via click or keypress to change the value of the input field.
@@ -323,6 +355,11 @@ When autocomplete is set to "automatic" the listbox will provide a filtered list
     type: 'string',
     description: 'Value to be applied to the combobox option. When omitted, value will default to the text content of the option.'
   },
+  {
+    name: 'formValue',
+    type: 'string',
+    description: 'An optional custom value to be used for form submissions when the "name" prop is provided for Combobox.'
+  },
   {
     name: 'disabled',
     type: 'boolean',

packages/react/__tests__/src/components/Combobox/index.js

@@ -873,6 +873,54 @@ test('should set selected value with "value" prop', () => {
   assertOptionIsSelected(1);
 });
 
+test('should not render hidden input when name is not provided', () => {
+  const wrapper = mount(
+    <Combobox value="Banana">
+      <ComboboxOption>Apple</ComboboxOption>
+      <ComboboxOption>Banana</ComboboxOption>
+      <ComboboxOption>Cantaloupe</ComboboxOption>
+    </Combobox>
+  );
+
+  expect(wrapper.find('input[type="hidden"]').exists()).toBeFalsy();
+});
+
+test('should render hidden input with value from text contents of ComboboxOption', () => {
+  const wrapper = mount(
+    <Combobox name="fruit" value="Banana">
+      <ComboboxOption>Apple</ComboboxOption>
+      <ComboboxOption>Banana</ComboboxOption>
+      <ComboboxOption>Cantaloupe</ComboboxOption>
+    </Combobox>
+  );
+
+  expect(wrapper.find('input[type="hidden"]').prop('value')).toEqual('Banana');
+});
+
+test('should render hidden input with value from value from ComboboxOption', () => {
+  const wrapper = mount(
+    <Combobox name="fruit" value="Banana">
+      <ComboboxOption value="Apple">🍎</ComboboxOption>
+      <ComboboxOption value="Banana">🍌</ComboboxOption>
+      <ComboboxOption value="Cantaloupe">🍈</ComboboxOption>
+    </Combobox>
+  );
+
+  expect(wrapper.find('input[type="hidden"]').prop('value')).toEqual('Banana');
+});
+
+test('should render hidden input with value from formValue from ComboboxOption', () => {
+  const wrapper = mount(
+    <Combobox name="fruit" value="Banana">
+      <ComboboxOption formValue="1">Apple</ComboboxOption>
+      <ComboboxOption formValue="2">Banana</ComboboxOption>
+      <ComboboxOption formValue="3">Cantaloupe</ComboboxOption>
+    </Combobox>
+  );
+
+  expect(wrapper.find('input[type="hidden"]').prop('value')).toEqual('2');
+});
+
 test('should support portal element for combobox listbos', () => {
   const element = document.createElement('div');
   const wrapper = mount(

packages/react/src/components/Combobox/Combobox.tsx

@@ -24,6 +24,7 @@ interface ComboboxOption {
   key?: string;
   label: string;
   value?: ComboboxValue;
+  formValue?: ComboboxValue;
   description?: string;
 }
 
@@ -91,6 +92,7 @@ const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(
       onKeyDown,
       onFocus,
       onBlur,
+      name,
       renderNoResults,
       portal,
       ...props
@@ -102,6 +104,7 @@ const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(
       Map<HTMLElement, ComboboxOptionState>
     >(new Map());
     const [selectedValue, setSelectedValue] = useState<string>(value || '');
+    const [formValue, setFormValue] = useState<string | undefined>('');
     const [open, setOpen] = useState(false);
     const [activeDescendant, setActiveDescendant] =
       useState<ListboxOption | null>(null);
@@ -153,7 +156,7 @@ const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(
       }
 
       if (open && autocomplete === 'automatic' && !selectedValue) {
-        // Fire an Home keydown event on listbox to ensure the first item is selected
+        // Fire a Home keydown event on listbox to ensure the first item is selected
         triggerListboxKeyDown(Home);
       }
     }, [open]);
@@ -371,7 +374,7 @@ const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(
         onActiveChange={handleActiveChange}
         ref={listboxRef}
         tabIndex={undefined}
-        aria-activedescendant=""
+        aria-activedescendant={undefined}
       >
         {comboboxOptions}
         {noMatchingOptions}
@@ -384,6 +387,7 @@ const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(
         className={classnames('Combobox', className)}
         ref={comboboxRef}
       >
+        {name && <input type="hidden" name={name} value={formValue} />}
         <label
           className={classnames('Field__label', {
             'Field__label--is-required': isRequired,
@@ -430,10 +434,12 @@ const Combobox = forwardRef<HTMLInputElement, ComboboxProps>(
         <ComboboxProvider
           autocomplete={autocomplete}
           inputValue={value}
+          formValue={formValue}
           selectedValue={selectedValue}
           matches={!isAutoComplete || defaultAutoCompleteMatches}
           matchingOptions={matchingOptions}
           setMatchingOptions={setMatchingOptions}
+          setFormValue={setFormValue}
         >
           {portal
             ? createPortal(

packages/react/src/components/Combobox/ComboboxContext.tsx

@@ -4,11 +4,13 @@ import { ComboboxValue } from './ComboboxOption';
 type ComboboxContext = {
   autocomplete: 'none' | 'manual' | 'automatic';
   inputValue: ComboboxValue;
+  formValue: ComboboxValue;
   selectedValue: ComboboxValue;
   matchingOptions: Map<HTMLElement, ComboboxOptionState>;
   setMatchingOptions: React.Dispatch<
     React.SetStateAction<Map<HTMLElement, ComboboxOptionState>>
   >;
+  setFormValue: React.Dispatch<React.SetStateAction<ComboboxValue>>;
   matches: (<T extends string = string>(value: T) => boolean) | boolean;
 };
 
@@ -26,41 +28,49 @@ type ComboboxProvider = {
 const ComboboxContext = createContext<ComboboxContext>({
   autocomplete: 'manual',
   inputValue: undefined,
+  formValue: undefined,
   selectedValue: undefined,
   matches: true,
   matchingOptions: new Map(),
-  setMatchingOptions: () => null
+  setMatchingOptions: () => null,
+  setFormValue: () => null
 });
 
 function ComboboxProvider({
   autocomplete,
   inputValue,
+  formValue,
   selectedValue,
   matches,
   matchingOptions,
   setMatchingOptions,
+  setFormValue,
   children
 }: ComboboxProvider): JSX.Element {
   const { Provider } = ComboboxContext as React.Context<ComboboxContext>;
   const contextValue: ComboboxContext = useMemo(
     () => ({
       autocomplete,
       inputValue,
+      formValue,
       selectedValue,
       matches:
         typeof matches === 'function' && !!inputValue
           ? (value) => matches(inputValue, value)
           : true,
       matchingOptions,
-      setMatchingOptions
+      setMatchingOptions,
+      setFormValue
     }),
     [
       autocomplete,
       inputValue,
+      formValue,
       selectedValue,
       matches,
       matchingOptions,
-      setMatchingOptions
+      setMatchingOptions,
+      setFormValue
     ]
   );
 

packages/react/src/components/Combobox/ComboboxOption.tsx

@@ -14,6 +14,7 @@ export type ComboboxValue = Exclude<ListboxValue, number>;
 interface ComboboxOptionProps extends React.HTMLAttributes<HTMLLIElement> {
   disabled?: boolean;
   value?: ComboboxValue;
+  formValue?: ComboboxValue;
   description?: ContentNode;
   children: string;
 }
@@ -58,13 +59,15 @@ const ComboboxOption = forwardRef<HTMLLIElement, ComboboxOptionProps>(
       id: propId,
       description,
       value: propValue,
+      formValue,
       ...props
     },
     ref
   ): JSX.Element | null => {
     const [id] = propId ? [propId] : useId(1, 'combobox-option');
     const { selected, active } = useListboxContext();
-    const { matches, setMatchingOptions } = useComboboxContext();
+    const { selectedValue, matches, setMatchingOptions, setFormValue } =
+      useComboboxContext();
     const comboboxOptionRef = useSharedRef<HTMLElement>(ref);
     const intersectionRef = useIntersectionRef<HTMLElement>(comboboxOptionRef, {
       root: null,
@@ -100,6 +103,19 @@ const ComboboxOption = forwardRef<HTMLLIElement, ComboboxOptionProps>(
       }
     }, [isActive]);
 
+    useEffect(() => {
+      const comboboxValue =
+        typeof propValue !== 'undefined'
+          ? propValue
+          : comboboxOptionRef.current?.innerText;
+
+      if (selectedValue === comboboxValue) {
+        setFormValue(
+          typeof formValue === 'undefined' ? comboboxValue : formValue
+        );
+      }
+    }, [selectedValue, formValue]);
+
     useEffect(() => {
       if (isMatching) {
         setMatchingOptions((options) => {