feat: add Listbox component (#3)

* make jest monorepo aware

* add @testing-library/jest-dom for custom matchers

This way we can use expect(element).toHaveAttribute(key, value?)

* abstract keys enum

* change type to unknown, because we don't know the return value

* update use-id hook, make it suspense aware

Thanks Reach UI!

* hoist the disposables collection

* add accessbility assertions for listbox

Also made it consistent for the Menu component and simplified some of the assertions

* add use-computed hook

This allows us re-render when hooks change, but also return a value. So this is a combination of useEffect and a useState value.

* add Listbox component

* bump dependencies

* add listbox example

* add lint-staged

This way we will only lint the files that have been staged and ready to be committed instead of the whole codebase

* add missing prevent defaults

* improve tests to verify that we can actually update the value of the listbox

* scroll the active listbox item into view

* small optimization, only focus "Nothing" on pointer leave when we are the active item

We used to always go to "Nothing" on pointer leave. And while this code
doesn't get called often, it *gets* called if you are using your arrow
keys and the mouse pointer is still over the list.

* bump dependencies

Also moved the tailwind dependencies to the root

* fix typo

* drop the default Transition inside the Menu and Listbox components

* update examples to reflect drop of default Transition wrapper

* rename Listbox.{Items,Item} to Listbox.{Options,Option}

Also rename all instances of `item` to `option` in tests and comments
and what have you...

* fix typo

* drop disabled prop, use aria-disabled only

packages/@headlessui-react/src/components/keyboard.ts

@@ -0,0 +1,19 @@
+// TODO: This must already exist somewhere, right? 🤔
+// Ref: https://www.w3.org/TR/uievents-key/#named-key-attribute-values
+export enum Keys {
+  Space = ' ',
+  Enter = 'Enter',
+  Escape = 'Escape',
+  Backspace = 'Backspace',
+
+  ArrowUp = 'ArrowUp',
+  ArrowDown = 'ArrowDown',
+
+  Home = 'Home',
+  End = 'End',
+
+  PageUp = 'PageUp',
+  PageDown = 'PageDown',
+
+  Tab = 'Tab',
+}

packages/@headlessui-react/src/components/listbox/listbox.tsx

@@ -0,0 +1,642 @@
+import * as React from 'react'
+
+import { useDisposables } from '../../hooks/use-disposables'
+import { useId } from '../../hooks/use-id'
+import { useIsoMorphicEffect } from '../../hooks/use-iso-morphic-effect'
+import { useComputed } from '../../hooks/use-computed'
+import { useSyncRefs } from '../../hooks/use-sync-refs'
+import { Props } from '../../types'
+import { forwardRefWithAs, render } from '../../utils/render'
+import { match } from '../../utils/match'
+import { disposables } from '../../utils/disposables'
+import { Keys } from '../keyboard'
+
+enum ListboxStates {
+  Open,
+  Closed,
+}
+
+type ListboxOptionDataRef = React.MutableRefObject<{
+  textValue?: string
+  disabled: boolean
+  value: unknown
+}>
+
+type StateDefinition = {
+  listboxState: ListboxStates
+  propsRef: React.MutableRefObject<{ value: unknown; onChange(value: unknown): void }>
+  labelRef: React.MutableRefObject<HTMLLabelElement | null>
+  buttonRef: React.MutableRefObject<HTMLButtonElement | null>
+  optionsRef: React.MutableRefObject<HTMLUListElement | null>
+  options: { id: string; dataRef: ListboxOptionDataRef }[]
+  searchQuery: string
+  activeOptionIndex: number | null
+}
+
+enum ActionTypes {
+  OpenListbox,
+  CloseListbox,
+
+  GoToOption,
+  Search,
+  ClearSearch,
+
+  RegisterOption,
+  UnregisterOption,
+}
+
+enum Focus {
+  First,
+  Previous,
+  Next,
+  Last,
+  Specific,
+  Nothing,
+}
+
+function calculateActiveOptionIndex(
+  state: StateDefinition,
+  focus: Focus,
+  id?: string
+): StateDefinition['activeOptionIndex'] {
+  if (state.options.length <= 0) return null
+
+  const options = state.options
+  const activeOptionIndex = state.activeOptionIndex ?? -1
+
+  const nextActiveIndex = match(focus, {
+    [Focus.First]: () => options.findIndex(option => !option.dataRef.current.disabled),
+    [Focus.Previous]: () => {
+      const idx = options
+        .slice()
+        .reverse()
+        .findIndex((option, idx, all) => {
+          if (activeOptionIndex !== -1 && all.length - idx - 1 >= activeOptionIndex) return false
+          return !option.dataRef.current.disabled
+        })
+      if (idx === -1) return idx
+      return options.length - 1 - idx
+    },
+    [Focus.Next]: () => {
+      return options.findIndex((option, idx) => {
+        if (idx <= activeOptionIndex) return false
+        return !option.dataRef.current.disabled
+      })
+    },
+    [Focus.Last]: () => {
+      const idx = options
+        .slice()
+        .reverse()
+        .findIndex(option => !option.dataRef.current.disabled)
+      if (idx === -1) return idx
+      return options.length - 1 - idx
+    },
+    [Focus.Specific]: () => options.findIndex(option => option.id === id),
+    [Focus.Nothing]: () => null,
+  })
+
+  if (nextActiveIndex === -1) return state.activeOptionIndex
+  return nextActiveIndex
+}
+
+type Actions =
+  | { type: ActionTypes.CloseListbox }
+  | { type: ActionTypes.OpenListbox }
+  | { type: ActionTypes.GoToOption; focus: Focus; id?: string }
+  | { type: ActionTypes.Search; value: string }
+  | { type: ActionTypes.ClearSearch }
+  | { type: ActionTypes.RegisterOption; id: string; dataRef: ListboxOptionDataRef }
+  | { type: ActionTypes.UnregisterOption; id: string }
+
+const reducers: {
+  [P in ActionTypes]: (
+    state: StateDefinition,
+    action: Extract<Actions, { type: P }>
+  ) => StateDefinition
+} = {
+  [ActionTypes.CloseListbox]: state => ({ ...state, listboxState: ListboxStates.Closed }),
+  [ActionTypes.OpenListbox]: state => ({ ...state, listboxState: ListboxStates.Open }),
+  [ActionTypes.GoToOption]: (state, action) => {
+    const activeOptionIndex = calculateActiveOptionIndex(state, action.focus, action.id)
+
+    if (state.searchQuery === '' && state.activeOptionIndex === activeOptionIndex) {
+      return state
+    }
+
+    return { ...state, searchQuery: '', activeOptionIndex }
+  },
+  [ActionTypes.Search]: (state, action) => {
+    const searchQuery = state.searchQuery + action.value
+    const match = state.options.findIndex(
+      option =>
+        !option.dataRef.current.disabled &&
+        option.dataRef.current.textValue?.startsWith(searchQuery)
+    )
+
+    if (match === -1 || match === state.activeOptionIndex) {
+      return { ...state, searchQuery }
+    }
+
+    return { ...state, searchQuery, activeOptionIndex: match }
+  },
+  [ActionTypes.ClearSearch]: state => ({ ...state, searchQuery: '' }),
+  [ActionTypes.RegisterOption]: (state, action) => ({
+    ...state,
+    options: [...state.options, { id: action.id, dataRef: action.dataRef }],
+  }),
+  [ActionTypes.UnregisterOption]: (state, action) => {
+    const nextOptions = state.options.slice()
+    const currentActiveOption =
+      state.activeOptionIndex !== null ? nextOptions[state.activeOptionIndex] : null
+
+    const idx = nextOptions.findIndex(a => a.id === action.id)
+
+    if (idx !== -1) nextOptions.splice(idx, 1)
+
+    return {
+      ...state,
+      options: nextOptions,
+      activeOptionIndex: (() => {
+        if (idx === state.activeOptionIndex) return null
+        if (currentActiveOption === null) return null
+
+        // If we removed the option before the actual active index, then it would be out of sync. To
+        // fix this, we will find the correct (new) index position.
+        return nextOptions.indexOf(currentActiveOption)
+      })(),
+    }
+  },
+}
+
+const ListboxContext = React.createContext<[StateDefinition, React.Dispatch<Actions>] | null>(null)
+
+function stateReducer(state: StateDefinition, action: Actions) {
+  return match(action.type, reducers, state, action)
+}
+
+function useListboxContext(component: string) {
+  const context = React.useContext(ListboxContext)
+  if (context === null) {
+    const err = new Error(`<${component} /> is missing a parent <${Listbox.name} /> component.`)
+    if (Error.captureStackTrace) Error.captureStackTrace(err, useListboxContext)
+    throw err
+  }
+  return context
+}
+
+// ---
+
+const DEFAULT_LISTBOX_TAG = React.Fragment
+
+type ListboxRenderPropArg = { open: boolean }
+
+export function Listbox<
+  TTag extends React.ElementType = typeof DEFAULT_LISTBOX_TAG,
+  TType = string
+>(props: Props<TTag, ListboxRenderPropArg> & { value: TType; onChange(value: TType): void }) {
+  const { value, onChange, ...passThroughProps } = props
+  const d = useDisposables()
+  const reducerBag = React.useReducer(stateReducer, {
+    listboxState: ListboxStates.Closed,
+    propsRef: { current: { value, onChange } },
+    labelRef: React.createRef(),
+    buttonRef: React.createRef(),
+    optionsRef: React.createRef(),
+    options: [],
+    searchQuery: '',
+    activeOptionIndex: null,
+  } as StateDefinition)
+  const [{ listboxState, propsRef, optionsRef, buttonRef }, dispatch] = reducerBag
+
+  useIsoMorphicEffect(() => {
+    propsRef.current.value = value
+  }, [value, propsRef])
+  useIsoMorphicEffect(() => {
+    propsRef.current.onChange = onChange
+  }, [onChange, propsRef])
+
+  React.useEffect(() => {
+    function handler(event: MouseEvent) {
+      if (listboxState !== ListboxStates.Open) return
+      if (buttonRef.current?.contains(event.target as HTMLElement)) return
+
+      if (!optionsRef.current?.contains(event.target as HTMLElement)) {
+        dispatch({ type: ActionTypes.CloseListbox })
+        if (!event.defaultPrevented) buttonRef.current?.focus()
+      }
+    }
+
+    window.addEventListener('click', handler)
+    return () => window.removeEventListener('click', handler)
+  }, [listboxState, optionsRef, buttonRef, d, dispatch])
+
+  const propsBag = React.useMemo<ListboxRenderPropArg>(
+    () => ({ open: listboxState === ListboxStates.Open }),
+    [listboxState]
+  )
+
+  return (
+    <ListboxContext.Provider value={reducerBag}>
+      {render(passThroughProps, propsBag, DEFAULT_LISTBOX_TAG)}
+    </ListboxContext.Provider>
+  )
+}
+
+// ---
+
+type ButtonPropsWeControl =
+  | 'ref'
+  | 'id'
+  | 'type'
+  | 'aria-haspopup'
+  | 'aria-controls'
+  | 'aria-expanded'
+  | 'aria-labelledby'
+  | 'onKeyDown'
+  | 'onFocus'
+  | 'onBlur'
+  | 'onPointerUp'
+
+const DEFAULT_BUTTON_TAG = 'button'
+
+type ButtonRenderPropArg = { open: boolean; focused: boolean }
+
+const Button = forwardRefWithAs(function Button<
+  TTag extends React.ElementType = typeof DEFAULT_BUTTON_TAG
+>(
+  props: Props<TTag, ButtonRenderPropArg, ButtonPropsWeControl>,
+  ref: React.Ref<HTMLButtonElement>
+) {
+  const [state, dispatch] = useListboxContext([Listbox.name, Button.name].join('.'))
+  const buttonRef = useSyncRefs(state.buttonRef, ref)
+  const [focused, setFocused] = React.useState(false)
+
+  const id = `headlessui-listbox-button-${useId()}`
+  const d = useDisposables()
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      switch (event.key) {
+        // Ref: https://www.w3.org/TR/wai-aria-practices-1.2/#keyboard-interaction-13
+
+        case Keys.Space:
+        case Keys.Enter:
+        case Keys.ArrowDown:
+          event.preventDefault()
+          dispatch({ type: ActionTypes.OpenListbox })
+          d.nextFrame(() => {
+            state.optionsRef.current?.focus()
+            if (!state.propsRef.current.value)
+              dispatch({ type: ActionTypes.GoToOption, focus: Focus.First })
+          })
+          break
+
+        case Keys.ArrowUp:
+          event.preventDefault()
+          dispatch({ type: ActionTypes.OpenListbox })
+          d.nextFrame(() => {
+            state.optionsRef.current?.focus()
+            if (!state.propsRef.current.value)
+              dispatch({ type: ActionTypes.GoToOption, focus: Focus.Last })
+          })
+          break
+      }
+    },
+    [dispatch, state, d]
+  )
+
+  const handlePointerUp = React.useCallback(
+    (event: MouseEvent) => {
+      if (state.listboxState === ListboxStates.Open) {
+        dispatch({ type: ActionTypes.CloseListbox })
+      } else {
+        event.preventDefault()
+        dispatch({ type: ActionTypes.OpenListbox })
+        d.nextFrame(() => state.optionsRef.current?.focus())
+      }
+    },
+    [dispatch, d, state]
+  )
+
+  const handleFocus = React.useCallback(() => {
+    if (state.listboxState === ListboxStates.Open) return state.optionsRef.current?.focus()
+    setFocused(true)
+  }, [state, setFocused])
+
+  const handleBlur = React.useCallback(() => setFocused(false), [setFocused])
+  const labelledby = useComputed(() => {
+    if (!state.labelRef.current) return undefined
+    return [state.labelRef.current.id, id].join(' ')
+  }, [state.labelRef.current, id])
+
+  const propsBag = React.useMemo<ButtonRenderPropArg>(
+    () => ({ open: state.listboxState === ListboxStates.Open, focused }),
+    [state, focused]
+  )
+  const passthroughProps = props
+  const propsWeControl = {
+    ref: buttonRef,
+    id,
+    type: 'button',
+    'aria-haspopup': true,
+    'aria-controls': state.optionsRef.current?.id,
+    'aria-expanded': state.listboxState === ListboxStates.Open ? true : undefined,
+    'aria-labelledby': labelledby,
+    onKeyDown: handleKeyDown,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    onPointerUp: handlePointerUp,
+  }
+
+  return render({ ...passthroughProps, ...propsWeControl }, propsBag, DEFAULT_BUTTON_TAG)
+})
+
+// ---
+
+type LabelPropsWeControl = 'id' | 'ref' | 'onPointerUp'
+
+const DEFAULT_LABEL_TAG = 'label'
+
+type LabelRenderPropArg = { open: boolean }
+
+function Label<TTag extends React.ElementType = typeof DEFAULT_LABEL_TAG>(
+  props: Props<TTag, LabelRenderPropArg, LabelPropsWeControl>
+) {
+  const [state] = useListboxContext([Listbox.name, Label.name].join('.'))
+  const id = `headlessui-listbox-label-${useId()}`
+
+  const handlePointerUp = React.useCallback(() => state.buttonRef.current?.focus(), [
+    state.buttonRef,
+  ])
+
+  const propsBag = React.useMemo<OptionsRenderPropArg>(
+    () => ({ open: state.listboxState === ListboxStates.Open }),
+    [state]
+  )
+  const propsWeControl = {
+    ref: state.labelRef,
+    id,
+    onPointerUp: handlePointerUp,
+  }
+  return render({ ...props, ...propsWeControl }, propsBag, DEFAULT_LABEL_TAG)
+}
+
+// ---
+
+type OptionsPropsWeControl =
+  | 'aria-activedescendant'
+  | 'aria-labelledby'
+  | 'id'
+  | 'onKeyDown'
+  | 'ref'
+  | 'role'
+  | 'tabIndex'
+
+const DEFAULT_OPTIONS_TAG = 'ul'
+
+type OptionsRenderPropArg = { open: boolean }
+
+type ListboxOptionsProp<TTag> = Props<TTag, OptionsRenderPropArg, OptionsPropsWeControl> & {
+  static?: boolean
+}
+
+const Options = forwardRefWithAs(function Options<
+  TTag extends React.ElementType = typeof DEFAULT_OPTIONS_TAG
+>(props: ListboxOptionsProp<TTag>, ref: React.Ref<HTMLUListElement>) {
+  const {
+    enter,
+    enterFrom,
+    enterTo,
+    leave,
+    leaveFrom,
+    leaveTo,
+    static: isStatic = false,
+    ...passthroughProps
+  } = props
+  const [state, dispatch] = useListboxContext([Listbox.name, Options.name].join('.'))
+  const optionsRef = useSyncRefs(state.optionsRef, ref)
+
+  const id = `headlessui-listbox-options-${useId()}`
+  const d = useDisposables()
+  const searchDisposables = useDisposables()
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLUListElement>) => {
+      searchDisposables.dispose()
+
+      switch (event.key) {
+        // Ref: https://www.w3.org/TR/wai-aria-practices-1.2/#keyboard-interaction-12
+
+        // @ts-expect-error Fallthrough is expected here
+        case Keys.Space:
+          if (state.searchQuery !== '') {
+            event.preventDefault()
+            return dispatch({ type: ActionTypes.Search, value: event.key })
+          }
+        // When in type ahead mode, fallthrough
+        case Keys.Enter:
+          event.preventDefault()
+          dispatch({ type: ActionTypes.CloseListbox })
+          if (state.activeOptionIndex !== null) {
+            const { dataRef } = state.options[state.activeOptionIndex]
+            state.propsRef.current.onChange(dataRef.current.value)
+          }
+          d.nextFrame(() => state.buttonRef.current?.focus())
+          break
+
+        case Keys.ArrowDown:
+          event.preventDefault()
+          return dispatch({ type: ActionTypes.GoToOption, focus: Focus.Next })
+
+        case Keys.ArrowUp:
+          event.preventDefault()
+          return dispatch({ type: ActionTypes.GoToOption, focus: Focus.Previous })
+
+        case Keys.Home:
+        case Keys.PageUp:
+          event.preventDefault()
+          return dispatch({ type: ActionTypes.GoToOption, focus: Focus.First })
+
+        case Keys.End:
+        case Keys.PageDown:
+          event.preventDefault()
+          return dispatch({ type: ActionTypes.GoToOption, focus: Focus.Last })
+
+        case Keys.Escape:
+          event.preventDefault()
+          dispatch({ type: ActionTypes.CloseListbox })
+          return d.nextFrame(() => state.buttonRef.current?.focus())
+
+        case Keys.Tab:
+          return event.preventDefault()
+
+        default:
+          if (event.key.length === 1) {
+            dispatch({ type: ActionTypes.Search, value: event.key })
+            searchDisposables.setTimeout(() => dispatch({ type: ActionTypes.ClearSearch }), 350)
+          }
+          break
+      }
+    },
+    [d, dispatch, searchDisposables, state]
+  )
+
+  const labelledby = useComputed(() => state.labelRef.current?.id ?? state.buttonRef.current?.id, [
+    state.labelRef.current,
+    state.buttonRef.current,
+  ])
+
+  const propsBag = React.useMemo<OptionsRenderPropArg>(
+    () => ({ open: state.listboxState === ListboxStates.Open }),
+    [state]
+  )
+  const propsWeControl = {
+    'aria-activedescendant':
+      state.activeOptionIndex === null ? undefined : state.options[state.activeOptionIndex]?.id,
+    'aria-labelledby': labelledby,
+    id,
+    onKeyDown: handleKeyDown,
+    role: 'listbox',
+    tabIndex: 0,
+  }
+
+  if (!isStatic && state.listboxState === ListboxStates.Closed) return null
+
+  return render(
+    { ...passthroughProps, ...propsWeControl, ...{ ref: optionsRef } },
+    propsBag,
+    DEFAULT_OPTIONS_TAG
+  )
+})
+
+// ---
+
+type ListboxOptionPropsWeControl =
+  | 'id'
+  | 'role'
+  | 'tabIndex'
+  | 'aria-disabled'
+  | 'aria-selected'
+  | 'onPointerLeave'
+  | 'onFocus'
+
+const DEFAULT_OPTION_TAG = 'li'
+
+type OptionRenderPropArg = { active: boolean; selected: boolean; disabled: boolean }
+
+function Option<TTag extends React.ElementType = typeof DEFAULT_OPTION_TAG, TType = string>(
+  props: Props<TTag, OptionRenderPropArg, ListboxOptionPropsWeControl | 'className'> & {
+    disabled?: boolean
+    value: TType
+
+    // Special treatment, can either be a string or a function that resolves to a string
+    className?: ((bag: OptionRenderPropArg) => string) | string
+  }
+) {
+  const { disabled = false, value, className, ...passthroughProps } = props
+  const [state, dispatch] = useListboxContext([Listbox.name, Option.name].join('.'))
+  const d = useDisposables()
+  const id = `headlessui-listbox-option-${useId()}`
+  const active =
+    state.activeOptionIndex !== null ? state.options[state.activeOptionIndex].id === id : false
+  const selected = state.propsRef.current.value === value
+
+  const bag = React.useRef<ListboxOptionDataRef['current']>({ disabled, value })
+
+  useIsoMorphicEffect(() => {
+    bag.current.disabled = disabled
+  }, [bag, disabled])
+  useIsoMorphicEffect(() => {
+    bag.current.value = value
+  }, [bag, value])
+  useIsoMorphicEffect(() => {
+    bag.current.textValue = document.getElementById(id)?.textContent?.toLowerCase()
+  }, [bag, id])
+
+  const select = React.useCallback(() => state.propsRef.current.onChange(value), [
+    state.propsRef,
+    value,
+  ])
+
+  useIsoMorphicEffect(() => {
+    dispatch({ type: ActionTypes.RegisterOption, id, dataRef: bag })
+    return () => dispatch({ type: ActionTypes.UnregisterOption, id })
+  }, [bag, id])
+
+  useIsoMorphicEffect(() => {
+    if (!selected) return
+    dispatch({ type: ActionTypes.GoToOption, focus: Focus.Specific, id })
+    document.getElementById(id)?.focus?.()
+  }, [])
+
+  useIsoMorphicEffect(() => {
+    if (!active) return
+    const d = disposables()
+    d.nextFrame(() => document.getElementById(id)?.scrollIntoView?.({ block: 'nearest' }))
+    return d.dispose
+  }, [active])
+
+  const handleClick = React.useCallback(
+    (event: { preventDefault: Function }) => {
+      if (disabled) return event.preventDefault()
+      select()
+      dispatch({ type: ActionTypes.CloseListbox })
+      d.nextFrame(() => state.buttonRef.current?.focus())
+    },
+    [d, dispatch, state.buttonRef, disabled, select]
+  )
+
+  const handleFocus = React.useCallback(() => {
+    if (disabled) return dispatch({ type: ActionTypes.GoToOption, focus: Focus.Nothing })
+    dispatch({ type: ActionTypes.GoToOption, focus: Focus.Specific, id })
+  }, [disabled, id, dispatch])
+
+  const handlePointerMove = React.useCallback(() => {
+    if (disabled) return
+    if (active) return
+    dispatch({ type: ActionTypes.GoToOption, focus: Focus.Specific, id })
+  }, [disabled, active, id, dispatch])
+
+  const handlePointerLeave = React.useCallback(() => {
+    if (disabled) return
+    if (!active) return
+    dispatch({ type: ActionTypes.GoToOption, focus: Focus.Nothing })
+  }, [disabled, active, dispatch])
+
+  const propsBag = React.useMemo(() => ({ active, selected, disabled }), [
+    active,
+    selected,
+    disabled,
+  ])
+  const propsWeControl = {
+    id,
+    role: 'option',
+    tabIndex: -1,
+    className: resolvePropValue(className, propsBag),
+    'aria-disabled': disabled === true ? true : undefined,
+    'aria-selected': selected === true ? true : undefined,
+    onClick: handleClick,
+    onFocus: handleFocus,
+    onPointerMove: handlePointerMove,
+    onPointerLeave: handlePointerLeave,
+  }
+
+  return render<TTag, OptionRenderPropArg>(
+    { ...passthroughProps, ...propsWeControl },
+    propsBag,
+    DEFAULT_OPTION_TAG
+  )
+}
+
+function resolvePropValue<TProperty, TBag>(property: TProperty, bag: TBag) {
+  if (property === undefined) return undefined
+  if (typeof property === 'function') return property(bag)
+  return property
+}
+
+// ---
+
+Listbox.Button = Button
+Listbox.Label = Label
+Listbox.Options = Options
+Listbox.Option = Option

packages/@headlessui-react/src/components/menu/menu.tsx

@@ -4,37 +4,17 @@ import * as React from 'react'
 import { Props } from '../../types'
 import { match } from '../../utils/match'
 import { forwardRefWithAs, render } from '../../utils/render'
-import { Transition, TransitionClasses } from '../transitions/transition'
 import { useDisposables } from '../../hooks/use-disposables'
 import { useIsoMorphicEffect } from '../../hooks/use-iso-morphic-effect'
 import { useSyncRefs } from '../../hooks/use-sync-refs'
 import { useId } from '../../hooks/use-id'
+import { Keys } from '../keyboard'
 
 enum MenuStates {
   Open,
   Closed,
 }
 
-// TODO: This must already exist somewhere, right? 🤔
-// Ref: https://www.w3.org/TR/uievents-key/#named-key-attribute-values
-enum Key {
-  Space = ' ',
-  Enter = 'Enter',
-  Escape = 'Escape',
-  Backspace = 'Backspace',
-
-  ArrowUp = 'ArrowUp',
-  ArrowDown = 'ArrowDown',
-
-  Home = 'Home',
-  End = 'End',
-
-  PageUp = 'PageUp',
-  PageDown = 'PageDown',
-
-  Tab = 'Tab',
-}
-
 type MenuItemDataRef = React.MutableRefObject<{ textValue?: string; disabled: boolean }>
 
 type StateDefinition = {
@@ -286,9 +266,9 @@ const Button = forwardRefWithAs(function Button<
       switch (event.key) {
         // Ref: https://www.w3.org/TR/wai-aria-practices-1.2/#keyboard-interaction-13
 
-        case Key.Space:
-        case Key.Enter:
-        case Key.ArrowDown:
+        case Keys.Space:
+        case Keys.Enter:
+        case Keys.ArrowDown:
           event.preventDefault()
           dispatch({ type: ActionTypes.OpenMenu })
           d.nextFrame(() => {
@@ -297,7 +277,7 @@ const Button = forwardRefWithAs(function Button<
           })
           break
 
-        case Key.ArrowUp:
+        case Keys.ArrowUp:
           event.preventDefault()
           dispatch({ type: ActionTypes.OpenMenu })
           d.nextFrame(() => {
@@ -369,20 +349,10 @@ type ItemsRenderPropArg = { open: boolean }
 const Items = forwardRefWithAs(function Items<
   TTag extends React.ElementType = typeof DEFAULT_ITEMS_TAG
 >(
-  props: Props<TTag, ItemsRenderPropArg, ItemsPropsWeControl> &
-    TransitionClasses & { static?: boolean },
+  props: Props<TTag, ItemsRenderPropArg, ItemsPropsWeControl> & { static?: boolean },
   ref: React.Ref<HTMLDivElement>
 ) {
-  const {
-    enter,
-    enterFrom,
-    enterTo,
-    leave,
-    leaveFrom,
-    leaveTo,
-    static: isStatic = false,
-    ...passthroughProps
-  } = props
+  const { static: isStatic = false, ...passthroughProps } = props
   const [state, dispatch] = useMenuContext([Menu.name, Items.name].join('.'))
   const itemsRef = useSyncRefs(state.itemsRef, ref)
 
@@ -397,12 +367,14 @@ const Items = forwardRefWithAs(function Items<
       switch (event.key) {
         // Ref: https://www.w3.org/TR/wai-aria-practices-1.2/#keyboard-interaction-12
 
-        // @ts-expect-error Falthrough is expected here
-        case Key.Space:
-          if (state.searchQuery !== '')
+        // @ts-expect-error Fallthrough is expected here
+        case Keys.Space:
+          if (state.searchQuery !== '') {
+            event.preventDefault()
             return dispatch({ type: ActionTypes.Search, value: event.key })
+          }
         // When in type ahead mode, fallthrough
-        case Key.Enter:
+        case Keys.Enter:
           event.preventDefault()
           dispatch({ type: ActionTypes.CloseMenu })
           if (state.activeItemIndex !== null) {
@@ -412,31 +384,31 @@ const Items = forwardRefWithAs(function Items<
           }
           break
 
-        case Key.ArrowDown:
+        case Keys.ArrowDown:
           event.preventDefault()
           return dispatch({ type: ActionTypes.GoToItem, focus: Focus.NextItem })
 
-        case Key.ArrowUp:
+        case Keys.ArrowUp:
           event.preventDefault()
           return dispatch({ type: ActionTypes.GoToItem, focus: Focus.PreviousItem })
 
-        case Key.Home:
-        case Key.PageUp:
+        case Keys.Home:
+        case Keys.PageUp:
           event.preventDefault()
           return dispatch({ type: ActionTypes.GoToItem, focus: Focus.FirstItem })
 
-        case Key.End:
-        case Key.PageDown:
+        case Keys.End:
+        case Keys.PageDown:
           event.preventDefault()
           return dispatch({ type: ActionTypes.GoToItem, focus: Focus.LastItem })
 
-        case Key.Escape:
+        case Keys.Escape:
           event.preventDefault()
           dispatch({ type: ActionTypes.CloseMenu })
           d.nextFrame(() => state.buttonRef.current?.focus())
           break
 
-        case Key.Tab:
+        case Keys.Tab:
           return event.preventDefault()
 
         default:
@@ -461,36 +433,12 @@ const Items = forwardRefWithAs(function Items<
     tabIndex: 0,
   }
 
-  if (isStatic) {
-    return render(
-      { ...passthroughProps, ...propsWeControl, ...{ ref: itemsRef } },
-      propsBag,
-      DEFAULT_ITEMS_TAG
-    )
-  }
+  if (!isStatic && state.menuState === MenuStates.Closed) return null
 
-  return (
-    <Transition
-      show={state.menuState === MenuStates.Open}
-      {...{ enter, enterFrom, enterTo, leave, leaveFrom, leaveTo }}
-    >
-      {ref =>
-        render(
-          {
-            ...passthroughProps,
-            ...propsWeControl,
-            ...{
-              ref(elementRef: HTMLDivElement) {
-                ref.current = elementRef
-                itemsRef(elementRef)
-              },
-            },
-          },
-          propsBag,
-          DEFAULT_ITEMS_TAG
-        )
-      }
-    </Transition>
+  return render(
+    { ...passthroughProps, ...propsWeControl, ...{ ref: itemsRef } },
+    propsBag,
+    DEFAULT_ITEMS_TAG
   )
 })
 
@@ -501,7 +449,6 @@ type MenuItemPropsWeControl =
   | 'role'
   | 'tabIndex'
   | 'aria-disabled'
-  | 'onPointerEnter'
   | 'onPointerLeave'
   | 'onFocus'
 
@@ -563,8 +510,9 @@ function Item<TTag extends React.ElementType = typeof DEFAULT_ITEM_TAG>(
 
   const handlePointerLeave = React.useCallback(() => {
     if (disabled) return
+    if (!active) return
     dispatch({ type: ActionTypes.GoToItem, focus: Focus.Nothing })
-  }, [disabled, dispatch])
+  }, [disabled, active, dispatch])
 
   const propsBag = React.useMemo(() => ({ active, disabled }), [active, disabled])
   const propsWeControl = {

packages/@headlessui-react/src/components/transitions/transition.tsx

@@ -8,7 +8,7 @@ import { useIsoMorphicEffect } from '../../hooks/use-iso-morphic-effect'
 import { match } from '../../utils/match'
 import { Reason, transition } from './utils/transition'
 
-type ID = number
+type ID = ReturnType<typeof useId>
 
 function useSplitClasses(classes: string = '') {
   return React.useMemo(() => classes.split(' ').filter(className => className.trim().length > 1), [

packages/@headlessui-react/src/hooks/use-computed.ts

@@ -0,0 +1,12 @@
+import * as React from 'react'
+import { useIsoMorphicEffect } from './use-iso-morphic-effect'
+
+export function useComputed<T>(cb: () => T, dependencies: React.DependencyList) {
+  const [value, setValue] = React.useState(cb)
+  const cbRef = React.useRef(cb)
+  useIsoMorphicEffect(() => {
+    cbRef.current = cb
+  }, [cb])
+  useIsoMorphicEffect(() => setValue(cbRef.current), [cbRef, setValue, ...dependencies])
+  return value
+}

packages/@headlessui-react/src/hooks/use-id.ts

@@ -1,11 +1,29 @@
 import * as React from 'react'
+import { useIsoMorphicEffect } from './use-iso-morphic-effect'
 
+// We used a "simple" approach first which worked for SSR and rehydration on the client. However we
+// didn't take care of the Suspense case. To fix this we used the approach the @reach-ui/auto-id
+// uses.
+//
+// Credits: https://github.com/reach/reach-ui/blob/develop/packages/auto-id/src/index.tsx
+
+let state = { serverHandoffComplete: false }
 let id = 0
 function generateId() {
   return ++id
 }
 
 export function useId() {
-  const [id] = React.useState(generateId)
-  return id
+  const [id, setId] = React.useState(state.serverHandoffComplete ? generateId : null)
+
+  useIsoMorphicEffect(() => {
+    if (id === null) setId(generateId())
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  React.useEffect(() => {
+    if (state.serverHandoffComplete === false) state.serverHandoffComplete = true
+  }, [])
+
+  return id != null ? '' + id : undefined
 }

packages/@headlessui-react/src/index.test.ts

@@ -5,5 +5,5 @@ import * as TailwindUI from './index'
  * the outside world that we didn't want!
  */
 it('should expose the correct components', () => {
-  expect(Object.keys(TailwindUI)).toEqual(['Transition', 'Menu'])
+  expect(Object.keys(TailwindUI)).toEqual(['Transition', 'Menu', 'Listbox'])
 })

packages/@headlessui-react/src/index.ts

@@ -1,2 +1,3 @@
 export * from './components/transitions/transition'
 export * from './components/menu/menu'
+export * from './components/listbox/listbox'

packages/@headlessui-react/src/test-utils/accessibility-assertions.ts

@@ -1,156 +1,181 @@
-export enum MenuButtonState {
-  Open,
-  Closed,
+function assertNever(x: never): never {
+  throw new Error('Unexpected object: ' + x)
 }
 
+// ---
+
+export function getMenuButton(): HTMLElement | null {
+  return document.querySelector('button,[role="button"]')
+}
+
+export function getMenuButtons(): HTMLElement[] {
+  return Array.from(document.querySelectorAll('button,[role="button"]'))
+}
+
+export function getMenu(): HTMLElement | null {
+  return document.querySelector('[role="menu"]')
+}
+
+export function getMenus(): HTMLElement[] {
+  return Array.from(document.querySelectorAll('[role="menu"]'))
+}
+
+export function getMenuItems(): HTMLElement[] {
+  return Array.from(document.querySelectorAll('[role="menuitem"]'))
+}
+
+// ---
+
 export enum MenuState {
   Open,
   Closed,
 }
 
-type MenuButtonOptions = { attributes?: Record<string, string | null>; textContent?: string } & (
-  | { state: MenuButtonState.Closed }
-  | { state: MenuButtonState.Open }
-)
-export function assertMenuButton(button: HTMLElement | null, options: MenuButtonOptions) {
+export function assertMenuButton(
+  options: {
+    attributes?: Record<string, string | null>
+    textContent?: string
+    state: MenuState
+  },
+  button = getMenuButton()
+) {
   try {
     if (button === null) return expect(button).not.toBe(null)
 
     // Ensure menu button have these properties
-    expect(button.hasAttribute('id')).toBe(true)
-    expect(button.hasAttribute('aria-haspopup')).toBe(true)
+    expect(button).toHaveAttribute('id')
+    expect(button).toHaveAttribute('aria-haspopup')
 
-    if (options.state === MenuButtonState.Open) {
-      expect(button.hasAttribute('aria-controls')).toBe(true)
-      expect(button.getAttribute('aria-expanded')).toBe('true')
-    }
+    switch (options.state) {
+      case MenuState.Open:
+        expect(button).toHaveAttribute('aria-controls')
+        expect(button).toHaveAttribute('aria-expanded', 'true')
+        break
 
-    if (options.state === MenuButtonState.Closed) {
-      expect(button.getAttribute('aria-controls')).toBeNull()
-      expect(button.getAttribute('aria-expanded')).toBeNull()
+      case MenuState.Closed:
+        expect(button).not.toHaveAttribute('aria-controls')
+        expect(button).not.toHaveAttribute('aria-expanded')
+        break
+
+      default:
+        assertNever(options.state)
     }
 
     if (options.textContent) {
-      expect(button.textContent?.trim()).toBe(options.textContent.trim())
+      expect(button).toHaveTextContent(options.textContent)
     }
 
     // Ensure menu button has the following attributes
     for (let attributeName in options.attributes) {
-      expect(button.getAttribute(attributeName)).toEqual(options.attributes[attributeName])
+      expect(button).toHaveAttribute(attributeName, options.attributes[attributeName])
     }
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertMenuButton)
-    }
+    Error.captureStackTrace(err, assertMenuButton)
     throw err
   }
 }
 
-export function assertMenuButtonLinkedWithMenu(
-  button: HTMLElement | null,
-  menu: HTMLElement | null
-) {
+export function assertMenuButtonLinkedWithMenu(button = getMenuButton(), menu = getMenu()) {
   try {
     if (button === null) return expect(button).not.toBe(null)
     if (menu === null) return expect(menu).not.toBe(null)
 
     // Ensure link between button & menu is correct
-    expect(button.getAttribute('aria-controls')).toBe(menu.getAttribute('id'))
-    expect(menu.getAttribute('aria-labelledby')).toBe(button.getAttribute('id'))
+    expect(button).toHaveAttribute('aria-controls', menu.getAttribute('id'))
+    expect(menu).toHaveAttribute('aria-labelledby', button.getAttribute('id'))
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertMenuButtonLinkedWithMenu)
-    }
+    Error.captureStackTrace(err, assertMenuButtonLinkedWithMenu)
     throw err
   }
 }
 
-export function assertMenuLinkedWithMenuItem(menu: HTMLElement | null, item: HTMLElement | null) {
+export function assertMenuLinkedWithMenuItem(item: HTMLElement | null, menu = getMenu()) {
   try {
     if (menu === null) return expect(menu).not.toBe(null)
     if (item === null) return expect(item).not.toBe(null)
 
     // Ensure link between menu & menu item is correct
-    expect(menu.getAttribute('aria-activedescendant')).toBe(item.getAttribute('id'))
+    expect(menu).toHaveAttribute('aria-activedescendant', item.getAttribute('id'))
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertMenuLinkedWithMenuItem)
-    }
+    Error.captureStackTrace(err, assertMenuLinkedWithMenuItem)
     throw err
   }
 }
 
-export function assertNoActiveMenuItem(menu: HTMLElement | null) {
+export function assertNoActiveMenuItem(menu = getMenu()) {
   try {
     if (menu === null) return expect(menu).not.toBe(null)
 
     // Ensure we don't have an active menu
-    expect(menu.hasAttribute('aria-activedescendant')).toBe(false)
+    expect(menu).not.toHaveAttribute('aria-activedescendant')
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertNoActiveMenuItem)
-    }
+    Error.captureStackTrace(err, assertNoActiveMenuItem)
     throw err
   }
 }
 
-type MenuOptions = { attributes?: Record<string, string | null>; textContent?: string } & (
-  | { state: MenuState.Closed }
-  | { state: MenuState.Open }
-)
-export function assertMenu(menu: HTMLElement | null, options: MenuOptions) {
+export function assertMenu(
+  options: {
+    attributes?: Record<string, string | null>
+    textContent?: string
+    state: MenuState
+  },
+  menu = getMenu()
+) {
   try {
-    if (options.state === MenuState.Open) {
-      if (menu === null) return expect(menu).not.toBe(null)
+    switch (options.state) {
+      case MenuState.Open:
+        if (menu === null) return expect(menu).not.toBe(null)
 
-      // Check that some attributes exists, doesn't really matter what the values are at this point in
-      // time, we just require them.
-      expect(menu.hasAttribute('aria-labelledby')).toBe(true)
+        // Check that some attributes exists, doesn't really matter what the values are at this point in
+        // time, we just require them.
+        expect(menu).toHaveAttribute('aria-labelledby')
 
-      // Check that we have the correct values for certain attributes
-      expect(menu.getAttribute('role')).toBe('menu')
+        // Check that we have the correct values for certain attributes
+        expect(menu).toHaveAttribute('role', 'menu')
 
-      // Check that the menu is focused
-      expect(document.activeElement).toBe(menu)
+        if (options.textContent) {
+          expect(menu).toHaveTextContent(options.textContent)
+        }
 
-      if (options.textContent) {
-        expect(menu.textContent?.trim()).toBe(options.textContent.trim())
-      }
+        // Ensure menu button has the following attributes
+        for (let attributeName in options.attributes) {
+          expect(menu).toHaveAttribute(attributeName, options.attributes[attributeName])
+        }
+        break
 
-      // Ensure menu button has the following attributes
-      for (let attributeName in options.attributes) {
-        expect(menu.getAttribute(attributeName)).toEqual(options.attributes[attributeName])
-      }
-    }
+      case MenuState.Closed:
+        expect(menu).toBe(null)
+        break
 
-    if (options.state === MenuState.Closed) {
-      expect(menu).toBeNull()
+      default:
+        assertNever(options.state)
     }
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertMenu)
-    }
+    Error.captureStackTrace(err, assertMenu)
     throw err
   }
 }
 
-type MenuItemOptions = { tag?: string; attributes?: Record<string, string | null> }
-export function assertMenuItem(item: HTMLElement | null, options?: MenuItemOptions) {
+export function assertMenuItem(
+  item: HTMLElement | null,
+  options?: { tag?: string; attributes?: Record<string, string | null> }
+) {
   try {
     if (item === null) return expect(item).not.toBe(null)
 
     // Check that some attributes exists, doesn't really matter what the values are at this point in
     // time, we just require them.
-    expect(item.hasAttribute('id')).toBe(true)
+    expect(item).toHaveAttribute('id')
 
     // Check that we have the correct values for certain attributes
-    expect(item.getAttribute('role')).toBe('menuitem')
-    expect(item.getAttribute('tabindex')).toBe('-1')
+    expect(item).toHaveAttribute('role', 'menuitem')
+    expect(item).toHaveAttribute('tabindex', '-1')
 
     // Ensure menu button has the following attributes
     if (options) {
       for (let attributeName in options.attributes) {
-        expect(item.getAttribute(attributeName)).toEqual(options.attributes[attributeName])
+        expect(item).toHaveAttribute(attributeName, options.attributes[attributeName])
       }
 
       if (options.tag) {
@@ -158,21 +183,301 @@ export function assertMenuItem(item: HTMLElement | null, options?: MenuItemOptio
       }
     }
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertMenuItem)
-    }
+    Error.captureStackTrace(err, assertMenuItem)
     throw err
   }
 }
 
+// ---
+
+export function getListboxLabel(): HTMLElement | null {
+  return document.querySelector('label,[id^="headlessui-listbox-label"]')
+}
+
+export function getListboxButton(): HTMLElement | null {
+  return document.querySelector('button,[role="button"]')
+}
+
+export function getListboxButtons(): HTMLElement[] {
+  return Array.from(document.querySelectorAll('button,[role="button"]'))
+}
+
+export function getListbox(): HTMLElement | null {
+  return document.querySelector('[role="listbox"]')
+}
+
+export function getListboxes(): HTMLElement[] {
+  return Array.from(document.querySelectorAll('[role="listbox"]'))
+}
+
+export function getListboxOptions(): HTMLElement[] {
+  return Array.from(document.querySelectorAll('[role="option"]'))
+}
+
+// ---
+
+export enum ListboxState {
+  Open,
+  Closed,
+}
+
+export function assertListbox(
+  options: {
+    attributes?: Record<string, string | null>
+    textContent?: string
+    state: ListboxState
+  },
+  listbox = getListbox()
+) {
+  try {
+    switch (options.state) {
+      case ListboxState.Open:
+        if (listbox === null) return expect(listbox).not.toBe(null)
+
+        // Check that some attributes exists, doesn't really matter what the values are at this point in
+        // time, we just require them.
+        expect(listbox).toHaveAttribute('aria-labelledby')
+
+        // Check that we have the correct values for certain attributes
+        expect(listbox).toHaveAttribute('role', 'listbox')
+
+        if (options.textContent) {
+          expect(listbox).toHaveTextContent(options.textContent)
+        }
+
+        // Ensure listbox button has the following attributes
+        for (let attributeName in options.attributes) {
+          expect(listbox).toHaveAttribute(attributeName, options.attributes[attributeName])
+        }
+        break
+
+      case ListboxState.Closed:
+        expect(listbox).toBe(null)
+        break
+
+      default:
+        assertNever(options.state)
+    }
+  } catch (err) {
+    Error.captureStackTrace(err, assertListbox)
+    throw err
+  }
+}
+
+export function assertListboxButton(
+  options: {
+    attributes?: Record<string, string | null>
+    textContent?: string
+    state: ListboxState
+  },
+  button = getListboxButton()
+) {
+  try {
+    if (button === null) return expect(button).not.toBe(null)
+
+    // Ensure menu button have these properties
+    expect(button).toHaveAttribute('id')
+    expect(button).toHaveAttribute('aria-haspopup')
+
+    switch (options.state) {
+      case ListboxState.Open:
+        expect(button).toHaveAttribute('aria-controls')
+        expect(button).toHaveAttribute('aria-expanded', 'true')
+        break
+
+      case ListboxState.Closed:
+        expect(button).not.toHaveAttribute('aria-controls')
+        expect(button).not.toHaveAttribute('aria-expanded')
+        break
+
+      default:
+        assertNever(options.state)
+    }
+
+    if (options.textContent) {
+      expect(button).toHaveTextContent(options.textContent)
+    }
+
+    // Ensure menu button has the following attributes
+    for (let attributeName in options.attributes) {
+      expect(button).toHaveAttribute(attributeName, options.attributes[attributeName])
+    }
+  } catch (err) {
+    Error.captureStackTrace(err, assertListboxButton)
+    throw err
+  }
+}
+
+export function assertListboxLabel(
+  options: {
+    attributes?: Record<string, string | null>
+    tag?: string
+    textContent?: string
+  },
+  label = getListboxLabel()
+) {
+  try {
+    if (label === null) return expect(label).not.toBe(null)
+
+    // Ensure menu button have these properties
+    expect(label).toHaveAttribute('id')
+
+    if (options.textContent) {
+      expect(label).toHaveTextContent(options.textContent)
+    }
+
+    if (options.tag) {
+      expect(label.tagName.toLowerCase()).toBe(options.tag)
+    }
+
+    // Ensure menu button has the following attributes
+    for (let attributeName in options.attributes) {
+      expect(label).toHaveAttribute(attributeName, options.attributes[attributeName])
+    }
+  } catch (err) {
+    Error.captureStackTrace(err, assertListboxLabel)
+    throw err
+  }
+}
+
+export function assertListboxButtonLinkedWithListbox(
+  button = getListboxButton(),
+  listbox = getListbox()
+) {
+  try {
+    if (button === null) return expect(button).not.toBe(null)
+    if (listbox === null) return expect(listbox).not.toBe(null)
+
+    // Ensure link between button & listbox is correct
+    expect(button).toHaveAttribute('aria-controls', listbox.getAttribute('id'))
+    expect(listbox).toHaveAttribute('aria-labelledby', button.getAttribute('id'))
+  } catch (err) {
+    Error.captureStackTrace(err, assertListboxButtonLinkedWithListbox)
+    throw err
+  }
+}
+
+export function assertListboxLabelLinkedWithListbox(
+  label = getListboxLabel(),
+  listbox = getListbox()
+) {
+  try {
+    if (label === null) return expect(label).not.toBe(null)
+    if (listbox === null) return expect(listbox).not.toBe(null)
+
+    expect(listbox).toHaveAttribute('aria-labelledby', label.getAttribute('id'))
+  } catch (err) {
+    Error.captureStackTrace(err, assertListboxLabelLinkedWithListbox)
+    throw err
+  }
+}
+
+export function assertListboxButtonLinkedWithListboxLabel(
+  button = getListboxButton(),
+  label = getListboxLabel()
+) {
+  try {
+    if (button === null) return expect(button).not.toBe(null)
+    if (label === null) return expect(label).not.toBe(null)
+
+    // Ensure link between button & label is correct
+    expect(button).toHaveAttribute('aria-labelledby', `${label.id} ${button.id}`)
+  } catch (err) {
+    Error.captureStackTrace(err, assertListboxButtonLinkedWithListboxLabel)
+    throw err
+  }
+}
+
+export function assertActiveListboxOption(item: HTMLElement | null, listbox = getListbox()) {
+  try {
+    if (listbox === null) return expect(listbox).not.toBe(null)
+    if (item === null) return expect(item).not.toBe(null)
+
+    // Ensure link between listbox & listbox item is correct
+    expect(listbox).toHaveAttribute('aria-activedescendant', item.getAttribute('id'))
+  } catch (err) {
+    Error.captureStackTrace(err, assertActiveListboxOption)
+    throw err
+  }
+}
+
+export function assertNoActiveListboxOption(listbox = getListbox()) {
+  try {
+    if (listbox === null) return expect(listbox).not.toBe(null)
+
+    // Ensure we don't have an active listbox
+    expect(listbox).not.toHaveAttribute('aria-activedescendant')
+  } catch (err) {
+    Error.captureStackTrace(err, assertNoActiveListboxOption)
+    throw err
+  }
+}
+
+export function assertNoSelectedListboxOption(items = getListboxOptions()) {
+  try {
+    for (let item of items) expect(item).not.toHaveAttribute('aria-selected')
+  } catch (err) {
+    Error.captureStackTrace(err, assertNoSelectedListboxOption)
+    throw err
+  }
+}
+
+export function assertListboxOption(
+  item: HTMLElement | null,
+  options?: {
+    tag?: string
+    attributes?: Record<string, string | null>
+    selected?: boolean
+  }
+) {
+  try {
+    if (item === null) return expect(item).not.toBe(null)
+
+    // Check that some attributes exists, doesn't really matter what the values are at this point in
+    // time, we just require them.
+    expect(item).toHaveAttribute('id')
+
+    // Check that we have the correct values for certain attributes
+    expect(item).toHaveAttribute('role', 'option')
+    expect(item).toHaveAttribute('tabindex', '-1')
+
+    // Ensure listbox button has the following attributes
+    if (!options) return
+
+    for (let attributeName in options.attributes) {
+      expect(item).toHaveAttribute(attributeName, options.attributes[attributeName])
+    }
+
+    if (options.tag) {
+      expect(item.tagName.toLowerCase()).toBe(options.tag)
+    }
+
+    if (options.selected != null) {
+      switch (options.selected) {
+        case true:
+          return expect(item).toHaveAttribute('aria-selected', 'true')
+
+        case false:
+          return expect(item).not.toHaveAttribute('aria-selected')
+
+        default:
+          assertNever(options.selected)
+      }
+    }
+  } catch (err) {
+    Error.captureStackTrace(err, assertListboxOption)
+    throw err
+  }
+}
+
+// ---
+
 export function assertActiveElement(element: HTMLElement | null) {
   try {
     if (element === null) return expect(element).not.toBe(null)
     expect(document.activeElement).toBe(element)
   } catch (err) {
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(err, assertActiveElement)
-    }
+    Error.captureStackTrace(err, assertActiveElement)
     throw err
   }
 }

packages/@headlessui-react/src/test-utils/interactions.ts

@@ -1,6 +1,8 @@
 import { fireEvent } from '@testing-library/react'
 import { disposables } from '../utils/disposables'
 
+const d = disposables()
+
 export const Keys: Record<string, Partial<KeyboardEvent>> = {
   Space: { key: ' ' },
   Enter: { key: 'Enter' },
@@ -34,7 +36,6 @@ export async function type(events: Partial<KeyboardEvent>[]) {
     if (document.activeElement === null) return expect(document.activeElement).not.toBe(null)
 
     const element = document.activeElement
-    const d = disposables()
 
     events.forEach(event => {
       fireEvent.keyDown(element, event)
@@ -60,8 +61,6 @@ export async function click(element: Document | Element | Window | Node | null)
   try {
     if (element === null) return expect(element).not.toBe(null)
 
-    const d = disposables()
-
     fireEvent.pointerDown(element)
     fireEvent.mouseDown(element)
     fireEvent.pointerUp(element)
@@ -79,8 +78,6 @@ export async function focus(element: Document | Element | Window | Node | null)
   try {
     if (element === null) return expect(element).not.toBe(null)
 
-    const d = disposables()
-
     fireEvent.focus(element)
 
     await new Promise(d.nextFrame)
@@ -92,7 +89,6 @@ export async function focus(element: Document | Element | Window | Node | null)
 export async function mouseEnter(element: Document | Element | Window | null) {
   try {
     if (element === null) return expect(element).not.toBe(null)
-    const d = disposables()
 
     fireEvent.pointerOver(element)
     fireEvent.pointerEnter(element)
@@ -108,7 +104,6 @@ export async function mouseEnter(element: Document | Element | Window | null) {
 export async function mouseMove(element: Document | Element | Window | null) {
   try {
     if (element === null) return expect(element).not.toBe(null)
-    const d = disposables()
 
     fireEvent.pointerMove(element)
     fireEvent.mouseMove(element)
@@ -123,7 +118,6 @@ export async function mouseMove(element: Document | Element | Window | null) {
 export async function mouseLeave(element: Document | Element | Window | null) {
   try {
     if (element === null) return expect(element).not.toBe(null)
-    const d = disposables()
 
     fireEvent.pointerOut(element)
     fireEvent.pointerLeave(element)

packages/@headlessui-react/src/test-utils/suppress-console-logs.ts

@@ -4,13 +4,13 @@ type FunctionPropertyNames<T> = {
   string
 
 export function suppressConsoleLogs<T extends unknown[]>(
-  cb: (...args: T) => void,
+  cb: (...args: T) => unknown,
   type: FunctionPropertyNames<typeof global.console> = 'error'
 ) {
   return (...args: T) => {
     const spy = jest.spyOn(global.console, type).mockImplementation(jest.fn())
 
-    return new Promise<void>((resolve, reject) => {
+    return new Promise<unknown>((resolve, reject) => {
       Promise.resolve(cb(...args)).then(resolve, reject)
     }).finally(() => spy.mockRestore())
   }