feat(headless): add combobox primitive

.changeset/tidy-combobox-primitive.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/package.json

@@ -6,68 +6,72 @@
   "type": "module",
   "exports": {
     "./accordion": {
-      "import": "./dist/primitives/accordion/index.js",
-      "types": "./dist/primitives/accordion/index.d.ts"
+      "types": "./dist/primitives/accordion/index.d.ts",
+      "import": "./dist/primitives/accordion/index.js"
     },
     "./button": {
-      "import": "./dist/primitives/button/index.js",
-      "types": "./dist/primitives/button/index.d.ts"
+      "types": "./dist/primitives/button/index.d.ts",
+      "import": "./dist/primitives/button/index.js"
     },
     "./tabs": {
-      "import": "./dist/primitives/tabs/index.js",
-      "types": "./dist/primitives/tabs/index.d.ts"
+      "types": "./dist/primitives/tabs/index.d.ts",
+      "import": "./dist/primitives/tabs/index.js"
     },
     "./tooltip": {
-      "import": "./dist/primitives/tooltip/index.js",
-      "types": "./dist/primitives/tooltip/index.d.ts"
+      "types": "./dist/primitives/tooltip/index.d.ts",
+      "import": "./dist/primitives/tooltip/index.js"
     },
     "./popover": {
-      "import": "./dist/primitives/popover/index.js",
-      "types": "./dist/primitives/popover/index.d.ts"
+      "types": "./dist/primitives/popover/index.d.ts",
+      "import": "./dist/primitives/popover/index.js"
     },
     "./select": {
-      "import": "./dist/primitives/select/index.js",
-      "types": "./dist/primitives/select/index.d.ts"
+      "types": "./dist/primitives/select/index.d.ts",
+      "import": "./dist/primitives/select/index.js"
     },
     "./menu": {
-      "import": "./dist/primitives/menu/index.js",
-      "types": "./dist/primitives/menu/index.d.ts"
+      "types": "./dist/primitives/menu/index.d.ts",
+      "import": "./dist/primitives/menu/index.js"
+    },
+    "./combobox": {
+      "types": "./dist/primitives/combobox/index.d.ts",
+      "import": "./dist/primitives/combobox/index.js"
     },
     "./autocomplete": {
-      "import": "./dist/primitives/autocomplete/index.js",
-      "types": "./dist/primitives/autocomplete/index.d.ts"
+      "types": "./dist/primitives/autocomplete/index.d.ts",
+      "import": "./dist/primitives/autocomplete/index.js"
     },
     "./collapsible": {
-      "import": "./dist/primitives/collapsible/index.js",
-      "types": "./dist/primitives/collapsible/index.d.ts"
+      "types": "./dist/primitives/collapsible/index.d.ts",
+      "import": "./dist/primitives/collapsible/index.js"
     },
     "./dialog": {
-      "import": "./dist/primitives/dialog/index.js",
-      "types": "./dist/primitives/dialog/index.d.ts"
+      "types": "./dist/primitives/dialog/index.d.ts",
+      "import": "./dist/primitives/dialog/index.js"
     },
     "./drawer": {
-      "import": "./dist/primitives/drawer/index.js",
-      "types": "./dist/primitives/drawer/index.d.ts"
+      "types": "./dist/primitives/drawer/index.d.ts",
+      "import": "./dist/primitives/drawer/index.js"
     },
     "./file-upload": {
-      "import": "./dist/primitives/file-upload/index.js",
-      "types": "./dist/primitives/file-upload/index.d.ts"
+      "types": "./dist/primitives/file-upload/index.d.ts",
+      "import": "./dist/primitives/file-upload/index.js"
     },
     "./flow": {
-      "import": "./dist/primitives/flow/index.js",
-      "types": "./dist/primitives/flow/index.d.ts"
+      "types": "./dist/primitives/flow/index.d.ts",
+      "import": "./dist/primitives/flow/index.js"
     },
     "./otp": {
-      "import": "./dist/primitives/otp/index.js",
-      "types": "./dist/primitives/otp/index.d.ts"
+      "types": "./dist/primitives/otp/index.d.ts",
+      "import": "./dist/primitives/otp/index.js"
     },
     "./hooks": {
-      "import": "./dist/hooks/index.js",
-      "types": "./dist/hooks/index.d.ts"
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js"
     },
     "./utils": {
-      "import": "./dist/utils/index.js",
-      "types": "./dist/utils/index.d.ts"
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
     }
   },
   "scripts": {

packages/headless/src/primitives/combobox/README.md

@@ -0,0 +1,38 @@
+# Combobox
+
+A headless single-selection input. Typing searches options; choosing one remembers its value.
+
+```tsx
+import { Combobox } from '@clerk/headless/combobox';
+
+<Combobox.Root>
+  <Combobox.Input aria-label='Fruit' />
+  <Combobox.Trigger aria-label='Show fruits' />
+  <Combobox.Positioner>
+    <Combobox.Popup>
+      <Combobox.Collection
+        items={['Apple', 'Banana']}
+        itemToStringLabel={item => item}
+      >
+        {item => (
+          <Combobox.Option
+            key={item}
+            value={item}
+          >
+            {item}
+            <Combobox.OptionIndicator>✓</Combobox.OptionIndicator>
+          </Combobox.Option>
+        )}
+      </Combobox.Collection>
+    </Combobox.Popup>
+  </Combobox.Positioner>
+</Combobox.Root>;
+```
+
+`value`, `defaultValue`, and `onValueChange` control the selected option. Clearing the input clears selection with `null`. `inputValue`, `defaultInputValue`, and `onInputValueChange` control search text separately.
+
+Dismissal restores the selected label. Reopening shows all options until typing starts. Hover and keyboard highlighting do not change selection.
+
+For search inside another popup, use `inline` with `List` and bind `open` to the outer popup. Closing clears search without clearing selection. Supply `defaultInputValue` when an initial selection's label differs from its value.
+
+Combobox owns its selection state and rendering parts independently of Autocomplete. Both use general headless utilities for rendering, controllable state, and transitions. Mosaic adds styling separately.

packages/headless/src/primitives/combobox/combobox-arrow.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { FloatingArrow, useMergeRefs } from '@floating-ui/react';
+import React from 'react';
+
+import { useComboboxContext } from './combobox-context';
+
+export type ComboboxArrowProps = Omit<React.ComponentPropsWithoutRef<typeof FloatingArrow>, 'context'>;
+
+export const ComboboxArrow = React.forwardRef<SVGSVGElement, ComboboxArrowProps>(function ComboboxArrow(props, ref) {
+  const { floatingContext, arrowRef, placement } = useComboboxContext();
+  const mergedRef = useMergeRefs([arrowRef, ref]);
+  const side = placement.split('-')[0];
+
+  return (
+    <FloatingArrow
+      data-side={side}
+      {...props}
+      ref={mergedRef}
+      context={floatingContext}
+    />
+  );
+});

packages/headless/src/primitives/combobox/combobox-collection.tsx

@@ -0,0 +1,20 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { useComboboxContext } from './combobox-context';
+
+export interface ComboboxCollectionProps<Item> {
+  items: readonly Item[];
+  itemToStringLabel: (item: Item) => string;
+  children: (item: Item) => ReactNode;
+  empty?: ReactNode;
+}
+
+/** Filters items using the search query rather than the selected label. */
+export function ComboboxCollection<Item>({ items, itemToStringLabel, children, empty }: ComboboxCollectionProps<Item>) {
+  const { filterQuery } = useComboboxContext();
+  const query = filterQuery.trim().toLocaleLowerCase();
+  const filtered = query ? items.filter(item => itemToStringLabel(item).toLocaleLowerCase().includes(query)) : items;
+  return <>{filtered.length ? filtered.map(children) : empty}</>;
+}

packages/headless/src/primitives/combobox/combobox-context.ts

@@ -0,0 +1,51 @@
+import type {
+  ExtendedRefs,
+  FloatingContext,
+  Placement,
+  ReferenceType,
+  UseInteractionsReturn,
+} from '@floating-ui/react';
+import { createContext, type CSSProperties, useContext } from 'react';
+
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface ComboboxContextValue {
+  open: boolean;
+  inputValue: string;
+  filterQuery: string;
+  selectedValue: string | null;
+  floatingContext: FloatingContext;
+  refs: ExtendedRefs<ReferenceType>;
+  floatingStyles: CSSProperties;
+  placement: Placement;
+  getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+  getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+  getItemProps: UseInteractionsReturn['getItemProps'];
+  activeIndex: number | null;
+  selectedIndex: number | null;
+  elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+  labelsRef: React.MutableRefObject<Array<string | null>>;
+  popupRef: React.RefObject<HTMLDivElement | null>;
+  triggerRef: React.MutableRefObject<HTMLButtonElement | null>;
+  arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+  valuesByIndexRef: React.MutableRefObject<Map<number, string>>;
+  setInlineMode: React.Dispatch<React.SetStateAction<boolean>>;
+  handleSelect: (value: string, index: number, label: string) => void;
+  handleInputChange: (value: string) => void;
+  setOpen: (open: boolean) => void;
+  focusInput: () => void;
+  popupId: string | undefined;
+  registerSelectedIndex: (index: number, value: string, label: string) => (() => void) | undefined;
+  mounted: boolean;
+  transitionProps: TransitionProps;
+}
+
+export const ComboboxContext = createContext<ComboboxContextValue | null>(null);
+
+export function useComboboxContext() {
+  const ctx = useContext(ComboboxContext);
+  if (!ctx) {
+    throw new Error('Combobox compound components must be used within <Combobox>');
+  }
+  return ctx;
+}

packages/headless/src/primitives/combobox/combobox-input.tsx

@@ -0,0 +1,60 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { useComboboxContext } from './combobox-context';
+
+export type ComboboxInputProps = ComponentProps<'input'>;
+
+export const ComboboxInput = React.forwardRef<HTMLInputElement, ComboboxInputProps>(function ComboboxInput(props, ref) {
+  const { render, ...otherProps } = props;
+  const {
+    open,
+    inputValue,
+    activeIndex,
+    refs,
+    getReferenceProps,
+    handleInputChange,
+    handleSelect,
+    labelsRef,
+    valuesByIndexRef,
+  } = useComboboxContext();
+
+  const state = { open };
+
+  const defaultProps = {
+    ...getReferenceProps({
+      value: inputValue,
+      'aria-autocomplete': 'list' as const,
+      onChange(event: React.ChangeEvent<HTMLInputElement>) {
+        handleInputChange(event.target.value);
+      },
+      onKeyDown(event: React.KeyboardEvent<HTMLInputElement>) {
+        if (event.key === 'Enter' && activeIndex != null) {
+          const value = valuesByIndexRef.current.get(activeIndex);
+          const label = labelsRef.current[activeIndex];
+          if (value != null) {
+            event.preventDefault();
+            handleSelect(value, activeIndex, label ?? value);
+          }
+        }
+      },
+    }),
+  };
+
+  return useRender({
+    defaultTagName: 'input',
+    render,
+    // floating-ui types `setReference` as a method signature, but at runtime it's
+    // a stable callback that doesn't use `this`, so the unbound-method check is a
+    // false positive here.
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    ref: [refs.setReference, ref],
+    state,
+    stateAttributesMapping: {
+      open: (v: boolean): Record<string, string> | null => (v ? { 'data-open': '' } : { 'data-closed': '' }),
+    },
+    props: mergeProps<'input'>(defaultProps, otherProps),
+  });
+});

packages/headless/src/primitives/combobox/combobox-list.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { FloatingList } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { useComboboxContext } from './combobox-context';
+
+export type ComboboxListProps = ComponentProps<'div'>;
+
+export const ComboboxList = React.forwardRef<HTMLDivElement, ComboboxListProps>(function ComboboxList(props, ref) {
+  const { render, ...otherProps } = props;
+  const { elementsRef, labelsRef, refs, getFloatingProps, setInlineMode } = useComboboxContext();
+
+  useEffect(() => {
+    setInlineMode(true);
+    return () => setInlineMode(false);
+  }, [setInlineMode]);
+
+  const floatingProps = getFloatingProps();
+  const wiredId = floatingProps.id;
+
+  const ownProps = {} satisfies DefaultProps<'div'>;
+
+  const defaultProps = { ...ownProps, ...floatingProps };
+
+  const merged = mergeProps<'div'>(defaultProps, otherProps);
+  // The wired id is owned by the primitive: a consumer-supplied id must not
+  // override it, or the aria-controls pairing would silently break.
+  if (wiredId != null) {
+    merged.id = wiredId;
+  }
+
+  return (
+    <FloatingList
+      elementsRef={elementsRef}
+      labelsRef={labelsRef}
+    >
+      {useRender({
+        defaultTagName: 'div',
+        render,
+        // floating-ui types `setFloating` as a method signature, but at runtime it's
+        // a stable callback that doesn't use `this`, so the unbound-method check is a
+        // false positive here.
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        ref: [refs.setFloating, ref],
+        props: merged,
+      })}
+    </FloatingList>
+  );
+});

packages/headless/src/primitives/combobox/combobox-option-context.ts

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+
+export const ComboboxOptionContext = createContext<boolean | null>(null);

packages/headless/src/primitives/combobox/combobox-option-indicator.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+import React, { useContext } from 'react';
+
+import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { ComboboxOptionContext } from './combobox-option-context';
+
+export type ComboboxOptionIndicatorProps = ComponentProps<'span'>;
+
+export const ComboboxOptionIndicator = React.forwardRef<HTMLSpanElement, ComboboxOptionIndicatorProps>(
+  function ComboboxOptionIndicator({ render, ...props }, ref) {
+    const selected = useContext(ComboboxOptionContext);
+    if (selected === null) {
+      throw new Error('Combobox.OptionIndicator must be used within Combobox.Option');
+    }
+    return useRender({
+      defaultTagName: 'span',
+      render,
+      ref,
+      enabled: selected,
+      props: mergeProps<'span'>({ 'aria-hidden': true }, props),
+    });
+  },
+);