@lovett/ui 0.0.10 → 0.1.0

package/src/combobox.tsx

@@ -0,0 +1,796 @@
+/**
+ * Combobox — a text input that filters a listbox; single- or multi-select.
+ *
+ * WAI-ARIA APG "editable combobox with list autocomplete": the `<input>` is
+ * `role="combobox"` with `aria-autocomplete="list"`, `aria-expanded`,
+ * `aria-controls` and `aria-activedescendant`; the popup is `role="listbox"`
+ * (`aria-multiselectable` in multi mode) of `role="option"` rows, optionally
+ * inside `role="group"` sections with a heading. DOM focus never leaves the
+ * input: a mousedown in the list is prevented, so clicking an option keeps
+ * the caret where it was.
+ *
+ * Filtering is client-side by default (case-insensitive substring over label
+ * and description) and starts only once the user TYPES — opening a
+ * single-select that already holds a value shows the whole list, not the one
+ * row matching the selected label. Async-friendly: pass `shouldFilter={false}`
+ * to show `options` exactly as given, read the query through
+ * `onInputValueChange`, fetch, and flip `loading` while you wait. The
+ * component never fetches anything itself.
+ *
+ * Single mode: picking an option sets it and closes; the input shows the
+ * selected label; the label text is selected on focus so typing replaces it;
+ * leaving the field (blur / outside click) with the text deliberately emptied
+ * clears the value (`onValueChange(null)`), while Escape closes and reverts.
+ * Multi mode: selected options render as chips ahead of the input; picking
+ * toggles and keeps the list open; Backspace on an empty input removes the
+ * last chip. Keep the selected options present in `options` (a chip whose
+ * option has scrolled out of an async result set falls back to its raw
+ * value as the label).
+ *
+ * Keyboard: ArrowDown / ArrowUp open the list and move the highlight
+ * (disabled options are skipped, no wrap), Enter picks the highlighted
+ * option, Escape closes (through the shared layer stack — a Combobox in a
+ * Popover in a Modal peels one layer per keypress), Tab and blur close.
+ * Home / End are left to the caret.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * the row / card / context-menu / palette pickers are all "popover + search +
+ * live counts", which is exactly `count` on each option). Second consumer is
+ * the workspace app: `lenses/sem-spec/components/location-autocomplete.tsx`
+ * hand-rolls this role, and TagChipInput carries the chip model this one
+ * generalises.
+ *
+ * Token discipline: the shell is `.input-shell` (INTERNAL `--bg-input` /
+ * `--border-input`, owned by styles.css); the listbox shares
+ * `LISTBOX_CLASS` + `POPOVER_SURFACE_STYLE` with Select; chips are public
+ * `--surface-overlay` on `--foreground`; counts and group headings
+ * `--text-muted`. Geometry from `useAnchoredPosition`, motion from
+ * `.ds-enter-pop` gated on `positioned` (prefers-reduced-motion honoured in
+ * styles.css).
+ *
+ * TODO(tokens): the type / size literals here (`text-[12px]` chips,
+ * `max-w-[12rem]`, `text-[12.5px]` and `text-[11px] tracking-[0.4px]` in
+ * the list, `minWidth: '6rem'`) mirror dropdown-menu.tsx and sit off the
+ * spacing scale; snap them once a type-scale token exists (review
+ * 2026-09-05, MINOR).
+ *
+ * Usage:
+ *
+ *   <Combobox
+ *     aria-label="Assignee"
+ *     placeholder="Search people…"
+ *     options={people.map((p) => ({ value: p.id, label: p.name, count: p.openTasks }))}
+ *     value={assigneeId}
+ *     onValueChange={setAssigneeId}
+ *   />
+ *
+ *   <Combobox
+ *     multiple
+ *     aria-label="Statuses"
+ *     groups={[{ id: 'open', label: 'Open' }, { id: 'closed', label: 'Closed' }]}
+ *     options={statuses}          // each with `group: 'open' | 'closed'`
+ *     value={selected}
+ *     onValueChange={setSelected}
+ *     renderOption={(o, { selected }) => <StatusRow status={o} checked={selected} />}
+ *   />
+ *
+ *   // Async: the consumer owns the query and the fetch.
+ *   <Combobox shouldFilter={false} loading={isFetching} options={results}
+ *             inputValue={query} onInputValueChange={setQuery} … />
+ */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type FocusEvent as ReactFocusEvent,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+  type RefAttributes,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { ChevronDown, Loader2, X } from 'lucide-react'
+import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { useLayer } from './lib/layer-stack'
+import {
+  useAnchoredPosition,
+  useOutsideClick,
+  type AnchorAlign,
+  type AnchorSide,
+} from './lib/anchor'
+import { POPOVER_SURFACE_STYLE } from './popover'
+import { LISTBOX_CLASS, ListboxOption } from './select'
+
+export type ComboboxSize = 'sm' | 'md'
+
+export interface ComboboxOption<T extends string = string> {
+  value: T
+  label: string
+  /** Secondary line under the label. Searched by the default filter. */
+  description?: string
+  /** Leading adornment — a Lucide icon, an avatar, a colour dot. */
+  icon?: ReactNode
+  /** Rendered but not selectable; skipped by the arrow keys. */
+  disabled?: boolean
+  /** Live count at the row's trailing edge (tasks per status, per assignee). */
+  count?: number
+  /** Key into `groups`. Ungrouped options render first. */
+  group?: string
+}
+
+export interface ComboboxGroup {
+  id: string
+  label: string
+}
+
+export interface ComboboxOptionState {
+  selected: boolean
+  highlighted: boolean
+  /** The query the list is currently filtered by ('' when unfiltered). */
+  query: string
+}
+
+interface ComboboxBaseProps<T extends string> {
+  options: ReadonlyArray<ComboboxOption<T>>
+  /**
+   * Group order and labels. Options whose `group` is not listed here render
+   * in a trailing group labelled by the key; omit `groups` entirely to
+   * derive groups from the options in order of first appearance.
+   */
+  groups?: ReadonlyArray<ComboboxGroup>
+  /** Shows a spinner in the shell and `loadingMessage` while the list is empty. */
+  loading?: boolean
+  placeholder?: string
+  /** Control height — matches `<Input inputSize>`. Default `md`. */
+  size?: ComboboxSize
+  disabled?: boolean
+  /** Error chrome (`is-error`) on the shell + `aria-invalid` on the input. */
+  error?: boolean
+  /** Controlled query text. Omit for internal state. */
+  inputValue?: string
+  defaultInputValue?: string
+  onInputValueChange?: (value: string) => void
+  /** Filter `options` by the query on the client. Default true; false for async. */
+  shouldFilter?: boolean
+  /** Custom match. Default: case-insensitive substring over label + description. */
+  filter?: (option: ComboboxOption<T>, query: string) => boolean
+  /** Default "No results". */
+  emptyMessage?: ReactNode
+  /** Default "Loading…". */
+  loadingMessage?: ReactNode
+  /** Replaces the default row body (icon / label / description / count). The check mark stays. */
+  renderOption?: (option: ComboboxOption<T>, state: ComboboxOptionState) => ReactNode
+  /** Controlled open state. Omit for internal state. */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Preferred side for the listbox. Default `bottom`; flips when it cannot fit. */
+  side?: AnchorSide
+  /** Default `start`. */
+  align?: AnchorAlign
+  /** id of the `<input>`, for `<label htmlFor>`. */
+  id?: string
+  /**
+   * Focus the input on mount. Also marks it `data-autofocus`: inside a
+   * Popover the popover does the focusing, once its content is positioned.
+   */
+  autoFocus?: boolean
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  /** Extra classes on the `.input-shell`. */
+  className?: string
+  /** Extra classes on the listbox surface. */
+  listboxClassName?: string
+}
+
+export interface ComboboxSingleProps<T extends string = string> extends ComboboxBaseProps<T> {
+  multiple?: false
+  /** Controlled value; `null` = nothing selected. */
+  value?: T | null
+  defaultValue?: T | null
+  /** `null` when the user empties the field and leaves it. */
+  onValueChange?: (value: T | null) => void
+}
+
+export interface ComboboxMultipleProps<T extends string = string> extends ComboboxBaseProps<T> {
+  multiple: true
+  value?: ReadonlyArray<T>
+  defaultValue?: ReadonlyArray<T>
+  onValueChange?: (value: T[]) => void
+}
+
+export type ComboboxProps<T extends string = string> =
+  | ComboboxSingleProps<T>
+  | ComboboxMultipleProps<T>
+
+const SHELL_SIZE_CLASS: Record<ComboboxSize, string> = {
+  sm: 'size-sm',
+  md: '',
+}
+
+/**
+ * Multi mode lets the shell grow with its chips. `.input-shell` is unlayered
+ * CSS (fixed height, `align-items: stretch`), which no layered Tailwind
+ * utility can override — so the overrides are inline, token-valued.
+ */
+const MULTI_SHELL_STYLE: Record<ComboboxSize, CSSProperties> = {
+  sm: {
+    height: 'auto',
+    minHeight: 'var(--ctrl-sm)',
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    gap: 'var(--space-1)',
+    paddingTop: 'var(--space-1)',
+    paddingBottom: 'var(--space-1)',
+  },
+  md: {
+    height: 'auto',
+    minHeight: 'var(--ctrl-md)',
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    gap: 'var(--space-1)',
+    paddingTop: 'var(--space-1)',
+    paddingBottom: 'var(--space-1)',
+  },
+}
+
+/**
+ * `.input-shell input` sets `min-width: 0`; once chips share the row the
+ * input needs room to type in before it wraps to its own line. Inline for
+ * the same cascade reason as above.
+ */
+const MULTI_INPUT_STYLE: CSSProperties = { minWidth: '6rem' }
+
+function defaultFilter(option: ComboboxOption<string>, query: string): boolean {
+  const needle = query.toLowerCase()
+  return (
+    option.label.toLowerCase().includes(needle) ||
+    (option.description?.toLowerCase().includes(needle) ?? false)
+  )
+}
+
+function sanitizeId(id: string): string {
+  return id.replace(/[^a-zA-Z0-9_-]/g, '')
+}
+
+interface FlatItem {
+  option: ComboboxOption<string>
+  /** Index into the flat, keyboard-navigable list. */
+  index: number
+}
+
+interface Section {
+  key: string
+  /** null = the ungrouped run at the top. */
+  label: string | null
+  items: FlatItem[]
+}
+
+const ComboboxImpl = forwardRef<HTMLInputElement, ComboboxProps<string>>(function Combobox(
+  props,
+  forwardedRef,
+) {
+  const {
+    options,
+    groups,
+    loading,
+    placeholder,
+    size = 'md',
+    disabled,
+    error,
+    inputValue: inputValueProp,
+    defaultInputValue = '',
+    onInputValueChange,
+    shouldFilter = true,
+    filter,
+    emptyMessage = 'No results',
+    loadingMessage = 'Loading…',
+    renderOption,
+    open: openProp,
+    onOpenChange,
+    side = 'bottom',
+    align = 'start',
+    id,
+    autoFocus,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    className,
+    listboxClassName,
+  } = props
+  const isMultiple = props.multiple === true
+
+  // ---- selection (normalised to a string[] internally) -------------------
+  const [uncontrolledSelection, setUncontrolledSelection] = useState<string[]>(() => {
+    if (props.multiple === true) return [...(props.defaultValue ?? [])]
+    return props.defaultValue == null ? [] : [props.defaultValue]
+  })
+  const isControlledValue = props.value !== undefined
+  const selection: ReadonlyArray<string> =
+    props.value === undefined
+      ? uncontrolledSelection
+      : props.multiple === true
+        ? props.value
+        : props.value === null
+          ? []
+          : [props.value]
+
+  const emit = (next: string[]) => {
+    if (!isControlledValue) setUncontrolledSelection(next)
+    if (props.multiple === true) props.onValueChange?.(next)
+    else props.onValueChange?.(next[0] ?? null)
+  }
+
+  // ---- query text ---------------------------------------------------------
+  const [uncontrolledInput, setUncontrolledInput] = useState(defaultInputValue)
+  const inputValue = inputValueProp ?? uncontrolledInput
+  const setInputValue = (next: string) => {
+    if (inputValueProp === undefined) setUncontrolledInput(next)
+    onInputValueChange?.(next)
+  }
+  // True once the user has typed since the list opened. Until then the list
+  // is unfiltered and (single mode) the input displays the selected label.
+  const [dirty, setDirty] = useState(false)
+
+  // ---- open state ---------------------------------------------------------
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(false)
+  const isControlledOpen = openProp !== undefined
+  const open = isControlledOpen ? Boolean(openProp) : uncontrolledOpen
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlledOpen) setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [isControlledOpen, onOpenChange],
+  )
+  // Mirrors `open` for handlers that may run twice for one gesture (outside
+  // pointerdown, then the blur it causes) — the second call is a no-op.
+  const openRef = useRef(open)
+  useLayoutEffect(() => {
+    openRef.current = open
+  })
+
+  const shellRef = useRef<HTMLDivElement | null>(null)
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const listboxRef = useRef<HTMLDivElement | null>(null)
+
+  const baseId = sanitizeId(useId())
+  const inputId = id ?? `combobox-${baseId}`
+  const listboxId = `combobox-listbox-${baseId}`
+  const optionId = (index: number) => `${listboxId}-opt-${index}`
+
+  const byValue = useMemo(() => {
+    const map = new Map<string, ComboboxOption<string>>()
+    for (const option of options) map.set(option.value, option)
+    return map
+  }, [options])
+  const selectedSingle = isMultiple ? undefined : byValue.get(selection[0] ?? '')
+
+  // ---- filtering + grouping ----------------------------------------------
+  const filterQuery = dirty ? inputValue.trim() : ''
+  const { sections, flat } = useMemo(() => {
+    const matches = filter ?? defaultFilter
+    const visible =
+      shouldFilter && filterQuery
+        ? options.filter((option) => matches(option, filterQuery))
+        : options
+
+    const byGroup = new Map<string | null, ComboboxOption<string>[]>()
+    for (const option of visible) {
+      const key = option.group ?? null
+      const list = byGroup.get(key) ?? []
+      list.push(option)
+      byGroup.set(key, list)
+    }
+
+    const order: Array<{ key: string | null; label: string | null }> = [{ key: null, label: null }]
+    if (groups) {
+      for (const group of groups) order.push({ key: group.id, label: group.label })
+      for (const key of byGroup.keys()) {
+        if (key !== null && !groups.some((group) => group.id === key)) {
+          order.push({ key, label: key })
+        }
+      }
+    } else {
+      for (const key of byGroup.keys()) if (key !== null) order.push({ key, label: key })
+    }
+
+    const flatList: ComboboxOption<string>[] = []
+    const sectionList: Section[] = []
+    for (const { key, label } of order) {
+      const members = byGroup.get(key)
+      if (!members || members.length === 0) continue
+      sectionList.push({
+        key: key ?? '__ungrouped',
+        label,
+        items: members.map((option) => ({ option, index: flatList.push(option) - 1 })),
+      })
+    }
+    return { sections: sectionList, flat: flatList }
+  }, [options, groups, filter, shouldFilter, filterQuery])
+
+  // ---- highlight ----------------------------------------------------------
+  const firstEnabled = flat.findIndex((option) => !option.disabled)
+  const selectedFlatIndex =
+    !isMultiple && !dirty && selectedSingle
+      ? flat.findIndex((option) => option.value === selectedSingle.value)
+      : -1
+  const [highlight, setHighlight] = useState<number | null>(null)
+  const activeIndex =
+    highlight !== null && highlight < flat.length
+      ? highlight
+      : selectedFlatIndex >= 0
+        ? selectedFlatIndex
+        : firstEnabled
+
+  const step = (from: number, direction: 1 | -1): number => {
+    for (let i = from + direction; i >= 0 && i < flat.length; i += direction) {
+      if (!flat[i]?.disabled) return i
+    }
+    return from
+  }
+
+  // ---- open / close / choose ---------------------------------------------
+  const openList = () => {
+    if (openRef.current) return
+    setHighlight(null)
+    setOpen(true)
+  }
+
+  /**
+   * `clearIfEmpty` — the user LEFT the field (blur / outside click): an
+   * emptied single-select clears its value. Escape and a pick pass false.
+   */
+  const closeList = (clearIfEmpty: boolean) => {
+    if (!openRef.current) return
+    openRef.current = false
+    if (!isMultiple && clearIfEmpty && dirty && inputValue.trim() === '' && selection.length > 0) {
+      emit([])
+    }
+    if (isMultiple && inputValue !== '') setInputValue('')
+    setDirty(false)
+    setHighlight(null)
+    setOpen(false)
+  }
+
+  const choose = (index: number) => {
+    const option = flat[index]
+    if (!option || option.disabled) return
+    if (isMultiple) {
+      const has = selection.includes(option.value)
+      emit(has ? selection.filter((value) => value !== option.value) : [...selection, option.value])
+      // Stays open; the query is kept so the user can keep toggling matches.
+    } else {
+      if (selection[0] !== option.value) emit([option.value])
+      closeList(false)
+    }
+    inputRef.current?.focus()
+  }
+
+  const removeChip = (value: string) => {
+    emit(selection.filter((candidate) => candidate !== value))
+    inputRef.current?.focus()
+  }
+
+  // ---- input events -------------------------------------------------------
+  const text = isMultiple || dirty ? inputValue : (selectedSingle?.label ?? '')
+
+  const handleChange = (next: string) => {
+    setInputValue(next)
+    setDirty(true)
+    setHighlight(null)
+    if (!openRef.current) setOpen(true)
+  }
+
+  const handleKeyDown = (event: ReactKeyboardEvent<HTMLInputElement>) => {
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault()
+        if (!open) openList()
+        else setHighlight(step(activeIndex, 1))
+        return
+      case 'ArrowUp':
+        event.preventDefault()
+        if (!open) openList()
+        else setHighlight(step(activeIndex, -1))
+        return
+      case 'Enter':
+        if (open) {
+          // Also keeps an enclosing <form> from submitting on a pick.
+          event.preventDefault()
+          if (activeIndex >= 0) choose(activeIndex)
+        }
+        return
+      case 'Backspace':
+        if (isMultiple && text === '' && selection.length > 0) {
+          event.preventDefault()
+          emit(selection.slice(0, -1))
+        }
+        return
+      case 'Tab':
+        if (open) closeList(true)
+        return
+      default:
+        // Escape is answered by the shared layer stack (topmost layer only).
+        return
+    }
+  }
+
+  const handleBlur = (event: ReactFocusEvent<HTMLInputElement>) => {
+    // A chip's remove button lives inside the shell; moving to it is not leaving.
+    if (event.relatedTarget instanceof Node && shellRef.current?.contains(event.relatedTarget)) {
+      return
+    }
+    closeList(true)
+  }
+
+  // ---- floating list ------------------------------------------------------
+  const {
+    ref: positionRef,
+    style: positionStyle,
+    placement,
+    positioned,
+  } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef: shellRef,
+    side,
+    align,
+    enabled: open,
+  })
+
+  const layer = useLayer({
+    enabled: open,
+    kind: 'popover',
+    elementRef: listboxRef,
+    onEscape: () => closeList(false),
+  })
+
+  useOutsideClick([shellRef, listboxRef], () => closeList(true), { enabled: open, layer })
+
+  const [shellWidth, setShellWidth] = useState<number | null>(null)
+  useLayoutEffect(() => {
+    if (!open) return
+    setShellWidth(shellRef.current?.offsetWidth ?? null)
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    listboxRef.current
+      ?.querySelector<HTMLElement>('[data-highlighted]')
+      ?.scrollIntoView({ block: 'nearest' })
+  }, [open, activeIndex])
+
+  useEffect(() => {
+    if (!autoFocus) return
+    const node = inputRef.current
+    if (!node) return
+    // Inside an anchored surface that is not positioned yet (a Popover's
+    // first frame is parked off-screen with `visibility: hidden`) a browser
+    // refuses the focus call outright. The surface focuses its
+    // `[data-autofocus]` control itself once positioned, so defer to it
+    // rather than fire a no-op that jsdom would wrongly honour.
+    if (node.closest('[data-positioned="false"]')) return
+    node.focus()
+    // Mount-only, like the DOM attribute it stands in for.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const inputRefs = useMemo(
+    () => composeRefs<HTMLInputElement>(forwardedRef, inputRef),
+    [forwardedRef],
+  )
+  const listboxRefs = useMemo(
+    () => composeRefs<HTMLDivElement>(listboxRef, positionRef),
+    [positionRef],
+  )
+
+  const chips = isMultiple ? selection : []
+  const hasChips = chips.length > 0
+  const shellStyle: CSSProperties | undefined = isMultiple
+    ? hasChips
+      ? { ...MULTI_SHELL_STYLE[size], paddingLeft: 'var(--space-2)' }
+      : MULTI_SHELL_STYLE[size]
+    : undefined
+
+  const renderItem = ({ option, index }: FlatItem) => {
+    const selected = selection.includes(option.value)
+    const highlighted = index === activeIndex
+    return (
+      <ListboxOption
+        key={option.value}
+        id={optionId(index)}
+        label={option.label}
+        description={option.description}
+        icon={option.icon}
+        count={option.count}
+        selected={selected}
+        highlighted={highlighted}
+        disabled={option.disabled}
+        onSelect={() => choose(index)}
+        onHighlight={() => setHighlight(index)}
+      >
+        {renderOption ? renderOption(option, { selected, highlighted, query: filterQuery }) : undefined}
+      </ListboxOption>
+    )
+  }
+
+  return (
+    <>
+      <div
+        ref={shellRef}
+        data-slot="combobox"
+        data-state={open ? 'open' : 'closed'}
+        data-size={size}
+        className={cn(
+          'input-shell has-trailing',
+          SHELL_SIZE_CLASS[size],
+          hasChips && 'has-leading',
+          error && 'is-error',
+          disabled && 'is-disabled',
+          className,
+        )}
+        style={shellStyle}
+      >
+        {chips.map((value) => {
+          const label = byValue.get(value)?.label ?? value
+          return (
+            <span
+              key={value}
+              data-slot="combobox-chip"
+              className="inline-flex items-center gap-1 rounded-[var(--radius-xs)] py-0.5 pl-2 pr-1 text-[12px] font-medium"
+              style={{
+                background: 'rgb(var(--surface-overlay))',
+                color: 'rgb(var(--foreground))',
+              }}
+            >
+              <span className="max-w-[12rem] truncate">{label}</span>
+              <button
+                type="button"
+                aria-label={`Remove ${label}`}
+                disabled={disabled}
+                onClick={() => removeChip(value)}
+                className="inline-flex h-4 w-4 items-center justify-center rounded-[var(--radius-xs)] transition-colors hover:bg-[rgb(var(--surface-overlay-strong))]"
+                style={{ color: 'rgb(var(--text-muted))' }}
+              >
+                <X className="h-3 w-3" aria-hidden="true" />
+              </button>
+            </span>
+          )
+        })}
+        <input
+          ref={inputRefs}
+          id={inputId}
+          type="text"
+          role="combobox"
+          aria-haspopup="listbox"
+          aria-expanded={open}
+          aria-controls={open ? listboxId : undefined}
+          aria-autocomplete="list"
+          aria-activedescendant={open && activeIndex >= 0 ? optionId(activeIndex) : undefined}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledby}
+          aria-invalid={error ? true : undefined}
+          autoComplete="off"
+          spellCheck={false}
+          disabled={disabled}
+          placeholder={hasChips ? '' : placeholder}
+          value={text}
+          data-slot="combobox-input"
+          data-autofocus={autoFocus ? '' : undefined}
+          style={isMultiple ? MULTI_INPUT_STYLE : undefined}
+          onChange={(event) => handleChange(event.target.value)}
+          onKeyDown={handleKeyDown}
+          onClick={openList}
+          // Single mode shows the selected label here; select it so typing
+          // replaces it rather than appending to it.
+          onFocus={(event) => event.currentTarget.select()}
+          onBlur={handleBlur}
+        />
+        {loading ? (
+          <span className="affix" aria-hidden="true">
+            <Loader2 className="h-4 w-4 animate-spin motion-reduce:animate-none" />
+          </span>
+        ) : null}
+        <button
+          type="button"
+          tabIndex={-1}
+          aria-label={open ? 'Close options' : 'Open options'}
+          disabled={disabled}
+          className="affix action"
+          // Keep focus in the input across the click.
+          onMouseDown={(event) => event.preventDefault()}
+          onClick={() => {
+            if (open) closeList(false)
+            else openList()
+            inputRef.current?.focus()
+          }}
+        >
+          <ChevronDown
+            className={cn(
+              'h-4 w-4 transition-transform duration-[var(--dur-fast)] ease-[var(--ease-out)] motion-reduce:transition-none',
+              open && 'rotate-180',
+            )}
+            aria-hidden="true"
+          />
+        </button>
+      </div>
+
+      {open && typeof document !== 'undefined'
+        ? createPortal(
+            <div
+              ref={listboxRefs}
+              id={listboxId}
+              role="listbox"
+              aria-multiselectable={isMultiple || undefined}
+              aria-busy={loading || undefined}
+              aria-label={ariaLabelledby ? undefined : ariaLabel}
+              aria-labelledby={ariaLabelledby}
+              tabIndex={-1}
+              data-slot="combobox-listbox"
+              data-state="open"
+              data-side={placement?.side}
+              data-align={placement?.align}
+              data-positioned={positioned ? 'true' : 'false'}
+              className={cn(LISTBOX_CLASS, positioned && 'ds-enter-pop', listboxClassName)}
+              style={{
+                ...positionStyle,
+                ...POPOVER_SURFACE_STYLE,
+                ...(shellWidth ? { minWidth: shellWidth } : undefined),
+              }}
+              // Keep DOM focus (and the caret) in the input across a click.
+              onMouseDown={(event) => event.preventDefault()}
+            >
+              {flat.length === 0 ? (
+                <div
+                  data-slot="combobox-empty"
+                  className="px-2.5 py-2 text-[12.5px]"
+                  style={{ color: 'rgb(var(--text-tertiary))' }}
+                >
+                  {loading ? loadingMessage : emptyMessage}
+                </div>
+              ) : (
+                sections.map((section) =>
+                  section.label === null ? (
+                    section.items.map(renderItem)
+                  ) : (
+                    <div
+                      key={section.key}
+                      role="group"
+                      aria-labelledby={`${listboxId}-group-${sanitizeId(section.key)}`}
+                      data-slot="combobox-group"
+                    >
+                      <div
+                        id={`${listboxId}-group-${sanitizeId(section.key)}`}
+                        data-slot="combobox-group-label"
+                        className="px-2.5 pb-1 pt-2 text-[11px] font-semibold uppercase tracking-[0.4px]"
+                        style={{ color: 'rgb(var(--text-muted))' }}
+                      >
+                        {section.label}
+                      </div>
+                      {section.items.map(renderItem)}
+                    </div>
+                  ),
+                )
+              )}
+            </div>,
+            document.body,
+          )
+        : null}
+    </>
+  )
+})
+
+/**
+ * `forwardRef` erases the component's type parameter (it is instantiated at
+ * `string` above). This assertion restores the generic signature so
+ * `onValueChange` narrows to the union of the option values a caller
+ * passed; it changes nothing at runtime.
+ */
+export const Combobox = ComboboxImpl as <T extends string = string>(
+  props: ComboboxProps<T> & RefAttributes<HTMLInputElement>,
+) => ReactElement | null