From d03fbb19f57ca3311b966ab3cf4603a5b981bf43 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 29 Mar 2024 15:41:12 +0100
Subject: [PATCH] Make the `Combobox` component `nullable` by default (#3064)

* remove `nullable` prop

* prevent selecting active option on blur

+ cleanup and adjust comments

* remove nullable from comments

* bump TypeScript to 5.4

This gives us `NoInfer<T>`!

* simplify types of `Combobox`

Now that `nullable` is gone, we can take another look at the type
definition. This in combination with the new `NoInfer` type makes types
drastically simpler and more correct.

* re-add `nullable` to prevent type issues

But let's mark it as deprecated to hint that something changed.

* update changelog

* improve `ByComparator` type

If we are just checking for `T extends null`, then
`{id:1,name:string}|null` will also be true and therefore we would
eventually return `string` instead of `"id" | "name"`.

To solve this, we first check if `NonNullable<T> extends never`, this
would be the case if `T` is `null`.

Otherwise, we know it's not just `null` but it can be something else
with or without `null`. To be sure, we use `keyof NonNullable<null>` to
get rid of the `null` part and to only keep the rest of the object (if
it's an object).

* ensure the `by` prop type handles `multiple` values correctly

This way the `by` prop will still compare single values that are present
inside the array.

This now also solves a pending TypeScript issue that we used to `//
@ts-expect-error` before.

* type uncontrolled `Combobox` components correctly

We have some tests that use uncontrolled components which means that we
can't infer the type from the `value` type.

* simplify `onChange` calls

Now that we don't infer the type when using the generic inside of
`onChange`, it means that we can use `onChange={setValue}` directly
because we don't have to worry about the updater function of `setValue`
anymore.

* correctly type `onChange`, by adding `null`

If you are in single value mode, then the `onChange` can (and will)
receive `null` as a value (when you clear the input field). We never
properly typed it so this fixes that.

In multiple value mode this won't happen, if anything the value will be
`[]` but not `null`.

* remove `nullable` prop from playground

* drop `nullable` mentions in tests
---
 package-lock.json                             |  20 ++-
 package.json                                  |   2 +-
 packages/@headlessui-react/CHANGELOG.md       |   1 +
 .../src/components/combobox/combobox.test.tsx |  71 +++-----
 .../src/components/combobox/combobox.tsx      | 169 ++++++------------
 .../src/hooks/use-by-comparator.ts            |   2 +-
 .../pages/combobox/combobox-virtualized.tsx   |   1 -
 7 files changed, 104 insertions(+), 162 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 4c2e013223..ed9f8defe9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -30,7 +30,7 @@
         "prettier-plugin-tailwindcss": "^0.5.7",
         "rimraf": "^3.0.2",
         "tslib": "^2.3.1",
-        "typescript": "^5.3.2"
+        "typescript": "^5.4.3"
       }
     },
     "node_modules/@adobe/css-tools": {
@@ -100,6 +100,19 @@
         "node": ">=18"
       }
     },
+    "node_modules/@arethetypeswrong/core/node_modules/typescript": {
+      "version": "5.3.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.3.3.tgz",
+      "integrity": "sha512-pXWcraxM0uxAS+tN0AG/BF2TyqmHO014Z070UsJ+pFvYuRSq8KH8DmWpnbXe0pEPDHXZV3FcAbJkijJ5oNEnWw==",
+      "dev": true,
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.23.5",
       "dev": true,
@@ -9653,9 +9666,10 @@
       }
     },
     "node_modules/typescript": {
-      "version": "5.3.3",
+      "version": "5.4.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.4.3.tgz",
+      "integrity": "sha512-KrPd3PKaCLr78MalgiwJnA25Nm8HAmdwN3mYUYZgG/wizIo9EainNVQI9/yDavtVFRN2h3k8uf3GLHuhDMgEHg==",
       "devOptional": true,
-      "license": "Apache-2.0",
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
diff --git a/package.json b/package.json
index 8f89cf0c7d..68164048dd 100644
--- a/package.json
+++ b/package.json
@@ -63,6 +63,6 @@
     "prettier-plugin-tailwindcss": "^0.5.7",
     "rimraf": "^3.0.2",
     "tslib": "^2.3.1",
-    "typescript": "^5.3.2"
+    "typescript": "^5.4.3"
   }
 }
diff --git a/packages/@headlessui-react/CHANGELOG.md b/packages/@headlessui-react/CHANGELOG.md
index c8291c4ebc..9086dd5168 100644
--- a/packages/@headlessui-react/CHANGELOG.md
+++ b/packages/@headlessui-react/CHANGELOG.md
@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Attempt form submission when pressing `Enter` on the `<Listbox.Button />` component ([#2972](https://github.com/tailwindlabs/headlessui/pull/2972))
+- Make the `Combobox` component `nullable` by default ([#3064](https://github.com/tailwindlabs/headlessui/pull/3064))
 
 ### Added
 
diff --git a/packages/@headlessui-react/src/components/combobox/combobox.test.tsx b/packages/@headlessui-react/src/components/combobox/combobox.test.tsx
index 8e24d69d0e..0e824d8562 100644
--- a/packages/@headlessui-react/src/components/combobox/combobox.test.tsx
+++ b/packages/@headlessui-react/src/components/combobox/combobox.test.tsx
@@ -387,10 +387,13 @@ describe('Rendering', () => {
         'should be possible to use completely new objects while rendering (single mode)',
         suppressConsoleLogs(async () => {
           function Example() {
-            let [value, setValue] = useState({ id: 2, name: 'Bob' })
+            let [value, setValue] = useState<{ id: number; name: string } | null>({
+              id: 2,
+              name: 'Bob',
+            })
 
             return (
-              <Combobox value={value} onChange={(value) => setValue(value)} by="id">
+              <Combobox value={value} onChange={setValue} by="id">
                 <Combobox.Button>Trigger</Combobox.Button>
                 <Combobox.Options>
                   <Combobox.Option value={{ id: 1, name: 'alice' }}>alice</Combobox.Option>
@@ -432,7 +435,7 @@ describe('Rendering', () => {
             let [value, setValue] = useState([{ id: 2, name: 'Bob' }])
 
             return (
-              <Combobox value={value} onChange={(value) => setValue(value)} by="id" multiple>
+              <Combobox value={value} onChange={setValue} by="id" multiple>
                 <Combobox.Button>Trigger</Combobox.Button>
                 <Combobox.Options>
                   <Combobox.Option value={{ id: 1, name: 'alice' }}>alice</Combobox.Option>
@@ -472,7 +475,7 @@ describe('Rendering', () => {
         ]
 
         render(
-          <Combobox name="assignee" by="id">
+          <Combobox<(typeof data)[number]> name="assignee" by="id">
             <Combobox.Input
               displayValue={(value: { name: string }) => value.name}
               onChange={NOOP}
@@ -499,7 +502,7 @@ describe('Rendering', () => {
         ]
 
         function Example() {
-          let [person, setPerson] = useState(data[1])
+          let [person, setPerson] = useState<(typeof data)[number] | null>(data[1])
 
           return (
             <Combobox value={person} onChange={setPerson} name="assignee" by="id">
@@ -546,7 +549,7 @@ describe('Rendering', () => {
         ]
 
         render(
-          <Combobox name="assignee" by="id">
+          <Combobox<(typeof data)[number]> name="assignee" by="id">
             <Combobox.Input onChange={NOOP} />
             <Combobox.Button />
             <Combobox.Options>
@@ -647,7 +650,7 @@ describe('Rendering', () => {
       'selecting an option puts the display value into Combobox.Input when displayValue is provided (when value is undefined)',
       suppressConsoleLogs(async () => {
         function Example() {
-          let [value, setValue] = useState(undefined)
+          let [value, setValue] = useState<null | undefined>(undefined)
 
           return (
             <Combobox value={value} onChange={setValue}>
@@ -692,7 +695,7 @@ describe('Rendering', () => {
 
           return (
             <>
-              <Combobox value={value} onChange={setValue} nullable>
+              <Combobox value={value} onChange={setValue}>
                 <Combobox.Input
                   onChange={NOOP}
                   displayValue={(str?: string) =>
@@ -766,7 +769,7 @@ describe('Rendering', () => {
       'should reflect the value in the input when the value changes and when you are typing',
       suppressConsoleLogs(async () => {
         function Example() {
-          let [value, setValue] = useState('bob')
+          let [value, setValue] = useState<string | null>('bob')
           let [_query, setQuery] = useState('')
 
           return (
@@ -1608,7 +1611,11 @@ describe('Rendering', () => {
             handleSubmission(Object.fromEntries(new FormData(e.target as HTMLFormElement)))
           }}
         >
-          <Combobox name="assignee" defaultValue={{ id: 2, name: 'bob', label: 'Bob' }} by="id">
+          <Combobox<(typeof data)[number]>
+            name="assignee"
+            defaultValue={{ id: 2, name: 'bob', label: 'Bob' }}
+            by="id"
+          >
             <Combobox.Button>{({ value }) => value?.name ?? 'Trigger'}</Combobox.Button>
             <Combobox.Input
               onChange={NOOP}
@@ -4093,34 +4100,13 @@ describe.each([{ virtual: true }, { virtual: false }])(
 
       describe('`Backspace` key', () => {
         it(
-          'should reset the value when the last character is removed, when in `nullable` mode',
+          'should reset the value when the last character is removed',
           suppressConsoleLogs(async () => {
             let handleChange = jest.fn()
             function Example() {
               let [value, setValue] = useState<string | null>('bob')
               let [, setQuery] = useState<string>('')
 
-              // return (
-              //   <MyCombobox
-              //     options={[
-              //       { value: 'alice', children: 'Alice' },
-              //       { value: 'bob', children: 'Bob' },
-              //       { value: 'charlie', children: 'Charlie' },
-              //     ]}
-              //     comboboxProps={{
-              //       value,
-              //       onChange: (value: any) => {
-              //         setValue(value)
-              //         handleChange(value)
-              //       },
-              //       nullable: true,
-              //     }}
-              //     inputProps={{
-              //       onChange: (event: any) => setQuery(event.target.value),
-              //     }}
-              //   />
-              // )
-
               return (
                 <Combobox
                   value={value}
@@ -4128,7 +4114,6 @@ describe.each([{ virtual: true }, { virtual: false }])(
                     setValue(value)
                     handleChange(value)
                   }}
-                  nullable
                 >
                   <Combobox.Input onChange={(event) => setQuery(event.target.value)} />
                   <Combobox.Button>Trigger</Combobox.Button>
@@ -4175,7 +4160,7 @@ describe.each([{ virtual: true }, { virtual: false }])(
             await press(Keys.Backspace)
             expect(getComboboxInput()?.value).toBe('')
 
-            // Verify that we don't have an selected option anymore since we are in `nullable` mode
+            // Verify that we don't have an selected option anymore
             assertNotActiveComboboxOption(options[1])
             assertNoSelectedComboboxOption()
 
@@ -4189,7 +4174,7 @@ describe.each([{ virtual: true }, { virtual: false }])(
       describe('`Any` key aka search', () => {
         type Option = { value: string; name: string; disabled: boolean }
         function Example(props: { people: { value: string; name: string; disabled: boolean }[] }) {
-          let [value, setValue] = useState<Option | undefined>(undefined)
+          let [value, setValue] = useState<Option | null | undefined>(undefined)
           let [query, setQuery] = useState<string>('')
           let filteredPeople =
             query === ''
@@ -4207,7 +4192,7 @@ describe.each([{ virtual: true }, { virtual: false }])(
                 }}
                 value={value}
                 by="value"
-                onChange={(value) => setValue(value)}
+                onChange={setValue}
               >
                 <Combobox.Input onChange={(event) => setQuery(event.target.value)} />
                 <Combobox.Button>Trigger</Combobox.Button>
@@ -5502,7 +5487,7 @@ describe('Multi-select', () => {
         let [value, setValue] = useState<string[]>(['bob', 'charlie'])
 
         return (
-          <Combobox value={value} onChange={(value) => setValue(value)} multiple>
+          <Combobox value={value} onChange={setValue} multiple>
             <Combobox.Input onChange={() => {}} />
             <Combobox.Button>Trigger</Combobox.Button>
             <Combobox.Options>
@@ -5538,7 +5523,7 @@ describe('Multi-select', () => {
         let [value, setValue] = useState<string[]>(['bob', 'charlie'])
 
         return (
-          <Combobox value={value} onChange={(value) => setValue(value)} multiple>
+          <Combobox value={value} onChange={setValue} multiple>
             <Combobox.Input onChange={() => {}} />
             <Combobox.Button>Trigger</Combobox.Button>
             <Combobox.Options>
@@ -5567,7 +5552,7 @@ describe('Multi-select', () => {
         let [value, setValue] = useState<string[]>(['bob', 'charlie'])
 
         return (
-          <Combobox value={value} onChange={(value) => setValue(value)} multiple>
+          <Combobox value={value} onChange={setValue} multiple>
             <Combobox.Input onChange={() => {}} />
             <Combobox.Button>Trigger</Combobox.Button>
             <Combobox.Options>
@@ -5600,7 +5585,7 @@ describe('Multi-select', () => {
         let [value, setValue] = useState<string[]>(['bob', 'charlie'])
 
         return (
-          <Combobox value={value} onChange={(value) => setValue(value)} multiple>
+          <Combobox value={value} onChange={setValue} multiple>
             <Combobox.Input onChange={() => {}} />
             <Combobox.Button>Trigger</Combobox.Button>
             <Combobox.Options>
@@ -5648,7 +5633,7 @@ describe('Multi-select', () => {
         let [value, setValue] = useState<string[]>([])
 
         return (
-          <Combobox value={value} onChange={(value) => setValue(value)} multiple>
+          <Combobox value={value} onChange={setValue} multiple>
             <Combobox.Input onChange={() => {}} />
             <Combobox.Button>Trigger</Combobox.Button>
             <Combobox.Options>
@@ -5798,7 +5783,7 @@ describe('Form compatibility', () => {
     let submits = jest.fn()
 
     function Example() {
-      let [value, setValue] = useState('home-delivery')
+      let [value, setValue] = useState<string | null>('home-delivery')
       return (
         <form
           onSubmit={(event) => {
@@ -5860,7 +5845,7 @@ describe('Form compatibility', () => {
     ]
 
     function Example() {
-      let [value, setValue] = useState(options[0])
+      let [value, setValue] = useState<(typeof options)[number] | null>(options[0])
 
       return (
         <form
diff --git a/packages/@headlessui-react/src/components/combobox/combobox.tsx b/packages/@headlessui-react/src/components/combobox/combobox.tsx
index 42bd0446fb..4e5f0073c6 100644
--- a/packages/@headlessui-react/src/components/combobox/combobox.tsx
+++ b/packages/@headlessui-react/src/components/combobox/combobox.tsx
@@ -48,7 +48,7 @@ import {
 import { FormFields } from '../../internal/form-fields'
 import { useProvidedId } from '../../internal/id'
 import { OpenClosedProvider, State, useOpenClosed } from '../../internal/open-closed'
-import type { EnsureArray, Expand, Props } from '../../types'
+import type { EnsureArray, Props } from '../../types'
 import { history } from '../../utils/active-element-history'
 import { isDisabledReactIssue7711 } from '../../utils/bugs'
 import { Focus, calculateActiveIndex } from '../../utils/calculate-active-index'
@@ -502,7 +502,6 @@ let ComboboxDataContext = createContext<
       disabled: boolean
       mode: ValueMode
       activeOptionIndex: number | null
-      nullable: boolean
       immediate: boolean
 
       virtual: { options: unknown[]; disabled: (value: unknown) => boolean } | null
@@ -552,85 +551,44 @@ type ComboboxRenderPropArg<TValue, TActive = TValue> = {
   value: TValue
 }
 
-type O = 'value' | 'defaultValue' | 'nullable' | 'multiple' | 'onChange' | 'by'
-
-type ComboboxValueProps<
-  TValue,
-  TNullable extends boolean | undefined,
-  TMultiple extends boolean | undefined,
-  TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG,
-> = Extract<
-  | ({
-      value?: EnsureArray<TValue>
-      defaultValue?: EnsureArray<TValue>
-      nullable: true // We ignore `nullable` in multiple mode
-      multiple: true
-      onChange?(value: EnsureArray<TValue>): void
-      by?: ByComparator<TValue>
-    } & Props<TTag, ComboboxRenderPropArg<EnsureArray<TValue>, TValue>, O>)
-  | ({
-      value?: TValue | null
-      defaultValue?: TValue | null
-      nullable: true
-      multiple?: false
-      onChange?(value: TValue | null): void
-      by?: ByComparator<TValue | null>
-    } & Expand<Props<TTag, ComboboxRenderPropArg<TValue | null>, O>>)
-  | ({
-      value?: EnsureArray<TValue>
-      defaultValue?: EnsureArray<TValue>
-      nullable?: false
-      multiple: true
-      onChange?(value: EnsureArray<TValue>): void
-      by?: ByComparator<TValue extends Array<infer U> ? U : TValue>
-    } & Expand<Props<TTag, ComboboxRenderPropArg<EnsureArray<TValue>, TValue>, O>>)
-  | ({
-      value?: TValue
-      nullable?: false
-      multiple?: false
-      defaultValue?: TValue
-      onChange?(value: TValue): void
-      by?: ByComparator<TValue>
-    } & Props<TTag, ComboboxRenderPropArg<TValue>, O>),
-  { nullable?: TNullable; multiple?: TMultiple }
->
-
 export type ComboboxProps<
   TValue,
-  TNullable extends boolean | undefined,
   TMultiple extends boolean | undefined,
   TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG,
-> = ComboboxValueProps<TValue, TNullable, TMultiple, TTag> & {
-  disabled?: boolean
-  __demoMode?: boolean
-  form?: string
-  name?: string
-  immediate?: boolean
-  virtual?: {
-    options: TValue[]
-    disabled?: (value: TValue) => boolean
-  } | null
-}
+> = Props<
+  TTag,
+  ComboboxRenderPropArg<NoInfer<TValue>>,
+  'value' | 'defaultValue' | 'multiple' | 'onChange' | 'by',
+  {
+    value?: TMultiple extends true ? EnsureArray<TValue> : TValue
+    defaultValue?: TMultiple extends true ? EnsureArray<NoInfer<TValue>> : NoInfer<TValue>
+
+    onChange?(
+      value: TMultiple extends true ? EnsureArray<NoInfer<TValue>> : NoInfer<TValue> | null
+    ): void
+    by?: ByComparator<
+      TMultiple extends true ? EnsureArray<NoInfer<TValue>>[number] : NoInfer<TValue>
+    >
 
-function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-  props: ComboboxProps<TValue, true, true, TTag>,
-  ref: Ref<HTMLElement>
-): JSX.Element
-function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-  props: ComboboxProps<TValue, true, false, TTag>,
-  ref: Ref<HTMLElement>
-): JSX.Element
-function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-  props: ComboboxProps<TValue, false, false, TTag>,
-  ref: Ref<HTMLElement>
-): JSX.Element
-function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-  props: ComboboxProps<TValue, false, true, TTag>,
-  ref: Ref<HTMLElement>
-): JSX.Element
+    /** @deprecated The `<Combobox />` is now nullable default */
+    nullable?: boolean
+
+    multiple?: TMultiple
+    disabled?: boolean
+    form?: string
+    name?: string
+    immediate?: boolean
+    virtual?: {
+      options: NoInfer<TValue>[]
+      disabled?: (value: NoInfer<TValue>) => boolean
+    } | null
+
+    __demoMode?: boolean
+  }
+>
 
 function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-  props: ComboboxProps<TValue, boolean | undefined, boolean | undefined, TTag>,
+  props: ComboboxProps<TValue, boolean | undefined, TTag>,
   ref: Ref<HTMLElement>
 ) {
   let providedDisabled = useDisabled()
@@ -643,7 +601,6 @@ function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_T
     by,
     disabled = providedDisabled || false,
     __demoMode = false,
-    nullable = false,
     multiple = false,
     immediate = false,
     virtual = null,
@@ -675,7 +632,6 @@ function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_T
   let optionsRef = useRef<_Data['optionsRef']['current']>(null)
 
   type TActualValue = true extends typeof multiple ? EnsureArray<TValue>[number] : TValue
-  // @ts-expect-error Eventually we'll want to tackle this, but for now this will do.
   let compare = useByComparator<TActualValue>(by)
 
   let calculateIndex = useEvent((value: TValue) => {
@@ -748,10 +704,9 @@ function ComboboxFn<TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_T
       compare,
       isSelected,
       isActive,
-      nullable,
       __demoMode,
     }),
-    [value, defaultValue, disabled, multiple, nullable, __demoMode, state, virtual]
+    [value, defaultValue, disabled, multiple, __demoMode, state, virtual]
   )
 
   useIsoMorphicEffect(() => {
@@ -1214,7 +1169,7 @@ function InputFn<
           event.stopPropagation()
         }
 
-        if (data.nullable && data.mode === ValueMode.Single) {
+        if (data.mode === ValueMode.Single) {
           // We want to clear the value when the user presses escape if and only if the current
           // value is not set (aka, they didn't select anything yet, or they cleared the input which
           // caused the value to be set to `null`). If the current value is set, then we want to
@@ -1247,15 +1202,13 @@ function InputFn<
     // options while typing won't work at all because we are still in "composing" mode.
     onChange?.(event)
 
-    // When the value becomes empty in a single value mode while being nullable then we want to clear
+    // When the value becomes empty in a single value mode then we want to clear
     // the option entirely.
     //
     // This is can happen when you press backspace, but also when you select all the text and press
     // ctrl/cmd+x.
-    if (data.nullable && data.mode === ValueMode.Single) {
-      if (event.target.value === '') {
-        clear()
-      }
+    if (data.mode === ValueMode.Single && event.target.value === '') {
+      clear()
     }
 
     // Open the combobox to show the results based on what the user has typed
@@ -1268,32 +1221,28 @@ function InputFn<
     isTyping.current = false
 
     // Focus is moved into the list, we don't want to close yet.
-    if (data.optionsRef.current?.contains(relatedTarget)) {
-      return
-    }
+    if (data.optionsRef.current?.contains(relatedTarget)) return
 
-    if (data.buttonRef.current?.contains(relatedTarget)) {
-      return
-    }
+    // Focus is moved to the button, we don't want to close yet.
+    if (data.buttonRef.current?.contains(relatedTarget)) return
 
+    // Focus is moved, but the combobox is not open. This can mean two things:
+    //
+    // 1. The combobox was never opened, so we don't have to do anything.
+    // 2. The combobox was closed and focus was moved already. At that point we
+    //    don't need to try and select the active option.
     if (data.comboboxState !== ComboboxState.Open) return
-    event.preventDefault()
 
-    if (data.mode === ValueMode.Single) {
-      // We want to clear the value when the user presses escape if and only if the current
-      // value is not set (aka, they didn't select anything yet, or they cleared the input which
-      // caused the value to be set to `null`). If the current value is set, then we want to
-      // fallback to that value when we press escape (this part is handled in the watcher that
-      // syncs the value with the input field again).
-      if (data.nullable && data.value === null) {
-        clear()
-      }
+    event.preventDefault()
 
-      // We do have a value, so let's select the active option, unless we were just going through
-      // the form and we opened it due to the focus event.
-      else if (data.activationTrigger !== ActivationTrigger.Focus) {
-        actions.selectActiveOption()
-      }
+    // We want to clear the value when the user presses escape or clicks outside
+    // the combobox if and only if the current value is not set (aka, they
+    // didn't select anything yet, or they cleared the input which caused the
+    // value to be set to `null`). If the current value is set, then we want to
+    // fallback to that value when we press escape (this part is handled in the
+    // watcher that syncs the value with the input field again).
+    if (data.mode === ValueMode.Single && data.value === null) {
+      clear()
     }
 
     return actions.closeCombobox()
@@ -1827,16 +1776,10 @@ function OptionFn<
 
 export interface _internal_ComponentCombobox extends HasDisplayName {
   <TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-    props: ComboboxProps<TValue, true, true, TTag> & RefProp<typeof ComboboxFn>
-  ): JSX.Element
-  <TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-    props: ComboboxProps<TValue, true, false, TTag> & RefProp<typeof ComboboxFn>
-  ): JSX.Element
-  <TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-    props: ComboboxProps<TValue, false, true, TTag> & RefProp<typeof ComboboxFn>
+    props: ComboboxProps<TValue, true, TTag> & RefProp<typeof ComboboxFn>
   ): JSX.Element
   <TValue, TTag extends ElementType = typeof DEFAULT_COMBOBOX_TAG>(
-    props: ComboboxProps<TValue, false, false, TTag> & RefProp<typeof ComboboxFn>
+    props: ComboboxProps<TValue, false, TTag> & RefProp<typeof ComboboxFn>
   ): JSX.Element
 }
 
diff --git a/packages/@headlessui-react/src/hooks/use-by-comparator.ts b/packages/@headlessui-react/src/hooks/use-by-comparator.ts
index fe5dd20b6e..f1f78003e4 100644
--- a/packages/@headlessui-react/src/hooks/use-by-comparator.ts
+++ b/packages/@headlessui-react/src/hooks/use-by-comparator.ts
@@ -1,7 +1,7 @@
 import { useCallback } from 'react'
 
 export type ByComparator<T> =
-  | (T extends null ? string : keyof T & string)
+  | (NonNullable<T> extends never ? string : keyof NonNullable<T> & string)
   | ((a: T, z: T) => boolean)
 
 function defaultBy<T>(a: T, z: T) {
diff --git a/playgrounds/react/pages/combobox/combobox-virtualized.tsx b/playgrounds/react/pages/combobox/combobox-virtualized.tsx
index 23f4c4bd40..700749eb19 100644
--- a/playgrounds/react/pages/combobox/combobox-virtualized.tsx
+++ b/playgrounds/react/pages/combobox/combobox-virtualized.tsx
@@ -66,7 +66,6 @@ function Example({ virtual = true, data, initial }: { virtual?: boolean; data; i
           <Combobox
             virtual={virtual ? { options: timezones } : undefined}
             value={activeTimezone}
-            nullable
             onChange={(value) => {
               setActiveTimezone(value)
               setQuery('')